forked from cerc-io/laconicd-deprecated
docs: testnet (#458)
* testnet docs * more changes * testnet and validators
This commit is contained in:
Federico Kunze Küllmer
GitHub
parent
fc46430e0f
commit
ea3ec3b7c6
@ -94,6 +94,16 @@ module.exports = {
|
||||
directory: true,
|
||||
path: '/guides/tools'
|
||||
},
|
||||
{
|
||||
title: 'Validators',
|
||||
directory: true,
|
||||
path: '/guides/validators'
|
||||
},
|
||||
{
|
||||
title: 'Key Management System',
|
||||
directory: true,
|
||||
path: '/guides/kms'
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
@ -115,9 +125,14 @@ module.exports = {
|
||||
title: 'Testnet',
|
||||
children: [
|
||||
{
|
||||
title: 'Guides',
|
||||
directory: true,
|
||||
path: '/testnet'
|
||||
title: 'Join Testnet',
|
||||
directory: false,
|
||||
path: '/testnet/join'
|
||||
},
|
||||
{
|
||||
title: 'Deploy Node on Cloud',
|
||||
directory: false,
|
||||
path: '/testnet/cloud_providers'
|
||||
},
|
||||
]
|
||||
},
|
||||
|
||||
@ -104,7 +104,7 @@ We are using [Algolia](https://www.algolia.com) to power full-text search. This
|
||||
1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml`.
|
||||
2. Edit API docs within the [Swagger Editor](https://editor.swagger.io/). Please refer to this [document](https://swagger.io/docs/specification/2-0/basic-structure/) for the correct structure in `.yaml`.
|
||||
3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `client/lcd/swagger-ui`.
|
||||
4. Compile gaiacli
|
||||
4. Compile ethermintd
|
||||
|
||||
```bash
|
||||
make install
|
||||
|
||||
@ -34,7 +34,3 @@ This matches Ethereum denomination of:
|
||||
|
||||
Ethermint is compatible with ERC20 tokens and other non-fungible token standards (EIP721, EIP1155)
|
||||
that are natively supported by the EVM.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn about the supported [JSON-RPC](./json_rpc.md) methods on Ethermint {hide}
|
||||
|
||||
@ -2,11 +2,18 @@
|
||||
order: 3
|
||||
-->
|
||||
|
||||
# Transactions
|
||||
# Transaction Lifecycle
|
||||
|
||||
This document describes the lifecycle of a transaction from creation to committed state changes on the EVM. {synopsis}
|
||||
|
||||
### Pre-requisite Readings
|
||||
|
||||
- [SDK transaction lifecycle](https://docs.cosmos.network/master/basics/tx-lifecycle.html) {prereq}
|
||||
|
||||
<!-- TODO: rewrite. This is not a lifecycle doc -->
|
||||
## Routing
|
||||
|
||||
Ethermint needs to parse and handle transactions routed for both the EVM and for the Cosmos hub. We
|
||||
Ethermint needs to parse and handle transactions routed for both the EVM and for Cosmos SDK modules. We
|
||||
attempt to achieve this by mimicking [geth's](https://github.com/ethereum/go-ethereum) `Transaction`
|
||||
structure and treat it as a unique Cosmos SDK message type. An Ethereum transaction is a single
|
||||
[`sdk.Msg`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#Msg). All relevant Ethereum
|
||||
@ -31,7 +38,3 @@ protocol supports different signer types based on the chain configuration params
|
||||
Ethermint supports all Ethereum `Signer`s up to the latest go-ethereum version (London, Berlin,
|
||||
EIP155, Homestead and Frontier). The chain will generate the latest `Signer` type depending on the
|
||||
`ChainConfig`.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn about how [gas](./gas.md) is used on Ethermint {hide}
|
||||
|
||||
34
docs/guides/kms/kms.md
Normal file
34
docs/guides/kms/kms.md
Normal file
@ -0,0 +1,34 @@
|
||||
<!--
|
||||
order: 1
|
||||
-->
|
||||
|
||||
# Tendermint KMS
|
||||
|
||||
[Tendermint KMS](https://github.com/iqlusioninc/tmkms) is a key management service that allows separating key management from Tendermint nodes. In addition it provides other advantages such as:
|
||||
|
||||
- Improved security and risk management policies
|
||||
- Unified API and support for various HSM (hardware security modules)
|
||||
- Double signing protection (software or hardware based)
|
||||
|
||||
It is recommended that the KMS service runs in a separate physical hosts.
|
||||
|
||||
## Building
|
||||
|
||||
Detailed build instructions can be found [here](https://github.com/iqlusioninc/tmkms#installation).
|
||||
|
||||
::: tip
|
||||
When compiling the KMS, ensure you have enabled the applicable features:
|
||||
:::
|
||||
|
||||
| Backend | Recommended Command line |
|
||||
|-------------------------|-----------------------------------|
|
||||
| YubiHSM | `cargo build --features yubihsm` |
|
||||
| Ledger + Tendermint App | `cargo build --features ledgertm` |
|
||||
|
||||
## Configuration
|
||||
|
||||
A KMS can be configured using the following HSMs:
|
||||
|
||||
### Using a YubiHSM
|
||||
|
||||
Detailed information on how to setup a KMS with YubiHSM2 can be found [here](https://github.com/iqlusioninc/tmkms/blob/master/README.yubihsm.md)
|
||||
@ -11,7 +11,7 @@ order: 1
|
||||
|
||||
## Automated Localnet (script)
|
||||
|
||||
You can customize the localtestnet script by changing values for convinience for example:
|
||||
You can customize the local testnet script by changing values for convenience for example:
|
||||
|
||||
```bash
|
||||
# customize the name of your key, the chain-id, moniker of the node, keyring backend, and log level
|
||||
@ -42,69 +42,100 @@ init.sh
|
||||
|
||||
This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
|
||||
|
||||
### Initialize node
|
||||
### Initialize the chain
|
||||
|
||||
Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the `init` subcommand:
|
||||
|
||||
```bash
|
||||
$MONIKER=testing
|
||||
$KEY=mykey
|
||||
$CHAINID="ethermint_9000-1"
|
||||
|
||||
# The argument $MONIKER is the custom username of your node, it should be human-readable.
|
||||
ethermintd init $MONIKER --chain-id=$CHAINID
|
||||
```
|
||||
|
||||
::: warning
|
||||
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
|
||||
::: tip
|
||||
You can [edit](./../../quickstart/binary.md#configuring-the-node) this `moniker` later by updating the `config.toml` file.
|
||||
:::
|
||||
|
||||
You can edit this `moniker` later, in the `$(HOME)/.ethermintd/config/config.toml` file:
|
||||
|
||||
```toml
|
||||
# A custom human readable name for this node
|
||||
moniker = "<your_custom_moniker>"
|
||||
```
|
||||
|
||||
You can edit the `$HOME/.ethermintd/config/app.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than the minimum gas prices:
|
||||
|
||||
```toml
|
||||
# This is a TOML config file.
|
||||
# For more information, see https://github.com/toml-lang/toml
|
||||
|
||||
##### main base config options #####
|
||||
|
||||
# The minimum gas prices a validator is willing to accept for processing a
|
||||
# transaction. A transaction's fees must meet the minimum of any denomination
|
||||
# specified in this config (e.g. 10aphoton).
|
||||
|
||||
minimum-gas-prices = ""
|
||||
```
|
||||
The command above creates all the configuration files needed for your node and validator to run, as well as a default genesis file, which defines the initial state of the network. All these [configuration files](./../../quickstart/binary.md#configuring-the-node) are in `~/.ethermintd` by default, but you can overwrite the location of this folder by passing the `--home` flag.
|
||||
|
||||
### Genesis Procedure
|
||||
|
||||
### Adding Genesis Accounts
|
||||
|
||||
Before starting the chain, you need to populate the state with at least one account using the [keyring](./../keys-wallets/keyring.md#add-keys):
|
||||
|
||||
```bash
|
||||
# Create a key to hold your account
|
||||
ethermintd keys add $KEY
|
||||
|
||||
# Add that key into the genesis.app_state.accounts array in the genesis file
|
||||
# NOTE: this command lets you set the number of coins. Make sure this account has some coins
|
||||
# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
|
||||
ethermintd add-genesis-account $(ethermintd keys show validator -a) 1000000000stake,10000000000aphoton
|
||||
|
||||
# Generate the transaction that creates your validator
|
||||
ethermintd gentx --name $KEY
|
||||
|
||||
# Add the generated bonding transaction to the genesis file
|
||||
ethermintd collect-gentxs
|
||||
|
||||
# Finally, check the correctness of the genesis.json file
|
||||
ethermintd validate-genesis
|
||||
ethermintd keys add my_validator --keyring-backend=test
|
||||
```
|
||||
|
||||
Once you have created a local account, go ahead and grant it some `aphoton` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
|
||||
|
||||
```bash
|
||||
ethermintd add-genesis-account my_validator 10000000000aphoton --keyring-backend test
|
||||
```
|
||||
|
||||
Now that your account has some tokens, you need to add a validator to your chain.
|
||||
|
||||
For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:
|
||||
|
||||
```bash
|
||||
# Create a gentx
|
||||
# NOTE: this command lets you set the number of coins.
|
||||
# Make sure this account has some coins with the genesis.app_state.staking.params.bond_denom denom
|
||||
ethermintd add-genesis-account my_validator 1000000000stake,10000000000aphoton
|
||||
```
|
||||
|
||||
A `gentx` does three things:
|
||||
|
||||
1. Registers the `validator` account you created as a validator operator account (i.e. the account that controls the validator).
|
||||
2. Self-delegates the provided `amount` of staking tokens.
|
||||
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `ethermintd init` command above.
|
||||
|
||||
For more information on `gentx`, use the following command:
|
||||
|
||||
```bash
|
||||
ethermintd gentx --help
|
||||
```
|
||||
|
||||
### Collecting `gentx`
|
||||
|
||||
By default, the genesis file do not contain any `gentxs`. A `gentx` is a transaction that bonds
|
||||
staking token present in the genesis file under `accounts` to a validator, essentially creating a
|
||||
validator at genesis. The chain will start as soon as more than 2/3rds of the validators (weighted
|
||||
by voting power) that are the recipient of a valid `gentx` come online after `genesis_time`.
|
||||
|
||||
A `gentx` can be added manually to the genesis file, or via the following command:
|
||||
|
||||
```bash
|
||||
# Add the gentx to the genesis file
|
||||
ethermintd collect-gentxs
|
||||
```
|
||||
|
||||
This command will add all the `gentxs` stored in `~/.ethermintd/config/gentx` to the genesis file.
|
||||
|
||||
### Run Testnet
|
||||
|
||||
Now its safe to start the daemon:
|
||||
Finally, check the correctness of the `genesis.json` file:
|
||||
|
||||
```bash
|
||||
ethermintd validate-genesis
|
||||
```
|
||||
|
||||
Now that everything is set up, you can finally start your node:
|
||||
|
||||
```bash
|
||||
ethermintd start
|
||||
```
|
||||
|
||||
You can then stop the node using Ctrl+C.
|
||||
:::tip
|
||||
To check all the available customizable options when running the node, use the `--help` flag.
|
||||
:::
|
||||
|
||||
You should see blocks come in.
|
||||
|
||||
The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them.
|
||||
|
||||
You can then stop the node using `Ctrl+C`.
|
||||
|
||||
@ -46,7 +46,7 @@ mv new_genesis.json genesis.json
|
||||
|
||||
Finally, go to the [reset data](./run_node.md#reset-data) section.
|
||||
|
||||
### Export State to a new Genesis locally
|
||||
### Export State
|
||||
|
||||
Ethermint can dump the entire application state to a JSON file. This, besides upgrades, can be
|
||||
useful for manual analysis of the state at a given height.
|
||||
|
||||
@ -1,11 +1,14 @@
|
||||
|
||||
<!--
|
||||
order: 5
|
||||
order: 4
|
||||
-->
|
||||
|
||||
# Validator Security
|
||||
# Validator Security Checklist
|
||||
|
||||
## Checklist
|
||||
Conduct a security checklist survey to go through the security measures of a validator {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Validator Security](./security.md) {prereq}
|
||||
|
||||
## Conduct Survey on General Controls of Hosting Data Centre
|
||||
|
||||
282
docs/guides/validators/faq.md
Normal file
282
docs/guides/validators/faq.md
Normal file
@ -0,0 +1,282 @@
|
||||
<!--
|
||||
order: 5
|
||||
-->
|
||||
|
||||
# Validator FAQ
|
||||
|
||||
## General Concepts
|
||||
|
||||
### What is a validator?
|
||||
|
||||
Ethermint is based on [Tendermint](https://tendermint.com/docs/introduction/what-is-tendermint.html), which relies on a set of validators 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'?
|
||||
|
||||
Ethermint is a public Proof-Of-Stake (PoS) blockchain, meaning that the weight of validators is determined by the amount of staking tokens (Photons) bonded as collateral. These Photons can be self-delegated directly by the validator or delegated to them by other Atom holders.
|
||||
|
||||
Any user in the system can declare their intention to become a validator by sending a `create-validator` transaction. From there, they become validator candidates.
|
||||
|
||||
The weight (i.e. voting power) of a validator determines whether or not they are an active validator. Initially, only the top 125 validators with the most voting power will be active validators.
|
||||
|
||||
### 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 users 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 a validator themselves. Atom holders can delegate Photons to a validator and obtain a part of their revenue in exchange (for more detail on how revenue is distributed, see [**What is the incentive to stake?**](#what-is-the-incentive-to-stake?) and [**What are validators commission?**](#what-are-validators-commission?) sections below).
|
||||
|
||||
Because they share revenue with their validators, delegators also share risks. Should a validator misbehave, each of their delegators will be partially slashed in proportion to their delegated 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. For more, read the [delegator's faq](https://hub.cosmos.network/main/delegators/delegator-faq.html).
|
||||
|
||||
## 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 this Tendermint `PubKey` is used to sign _prevotes_ and _precommits_.
|
||||
- **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 delegate, unbond, claim rewards, and participate in governance.
|
||||
- **Validator's name (moniker)**
|
||||
- **Validator's website (Optional)**
|
||||
- **Validator's description (Optional)**
|
||||
- **Initial commission rate**: The commission rate on block rewards and fees charged to delegators.
|
||||
- **Maximum commission:** The maximum commission rate which this validator can charge. This parameter cannot be changed after `create-validator` is processed.
|
||||
- **Commission max change rate:** The maximum daily increase of the validator commission. This parameter cannot be changed after `create-validator` is processed.
|
||||
- **Minimum self-delegation:** Minimum amount of Photons the validator needs to have bonded at all time. If the validator's self-delegated stake falls below this limit, their entire staking pool will unbond.
|
||||
|
||||
Once a validator is created, Atom holders can delegate atoms to them, effectively adding stake to their pool. The total stake of an address is the combination of Photons bonded by delegators and Photons self-bonded by the entity which designated themselves.
|
||||
|
||||
Out of all validator candidates that signaled themselves, the 125 with the most total stake are the ones who are designated as validators. They become **validators** If a validator's total stake falls below the top 125 then that validator loses their validator privileges: they don't participate in consensus and generate rewards any more. Over time, the maximum number of validators may be increased via on-chain governance proposal.
|
||||
|
||||
## 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 on the [documentation](../../testnet/join.md) and on the official [`testnets`](https://github.com/tharsis/testnets) repository.
|
||||
|
||||
### 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 consensus votes.
|
||||
- It is associated with a public key `ethvalconspub` (Get this value with `ethermintd tendermint show-validator`)
|
||||
- It is generated when the node is created with `ethermintd init`.
|
||||
- **Application key**: This key is created from `ethermintd` and used to sign transactions. Application keys are associated with a public key prefixed by `ethpub` and an address prefixed by `eth`. Both are derived from account keys generated by `ethermintd keys add`.
|
||||
|
||||
Note: A validator's operator key is directly tied to an application key, but
|
||||
uses reserved prefixes solely for this purpose: `ethvaloper` and `ethvaloperpub`
|
||||
|
||||
### What are the different states a validator can be in?
|
||||
|
||||
After a validator is created with a `create-validator` transaction, they can be in three states:
|
||||
|
||||
- `in validator set`: Validator is in the active set and participates in consensus. Validator is earning rewards and can be slashed for misbehaviour.
|
||||
- `jailed`: Validator misbehaved and is in jail, i.e. outside of the validator set. If the jailing is due to being offline for too long, the validator can send an `unjail` transaction in order to re-enter the validator set. If the jailing is due to double signing, the validator cannot unjail.
|
||||
- `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 Photons to this validator. Un-delegating from an `unbonded` validator is immediate.
|
||||
|
||||
### What is 'self-delegation'? How can I increase my 'self-delegation'?
|
||||
|
||||
Self-delegation is delegation from a validator to themselves. This amount can be increases by sending a `delegate` transaction from your validator's `application` application key.
|
||||
|
||||
### Is there a minimum amount of Photons that must be delegated to be an active (=bonded) validator?
|
||||
|
||||
The minimum is `1 aphoton`.
|
||||
|
||||
### 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-delegated Photons:** Number of Photons a validator self-delegated to themselves. A validator with a higher amount of self-delegated Photons has more skin in the game, making them more liable for their actions.
|
||||
- **Amount of delegated Photons:** Total number of Photons delegated to a validator. A high voting power shows that the community trusts this validator, but it also means that this validator is a bigger target for hackers. Bigger validators also decrease the decentralization of the network.
|
||||
- **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, 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 themselves. For more on due diligence, see [this blog post](https://medium.com/@interchain_io/3d0faf10ce6f)
|
||||
|
||||
## Responsibilities
|
||||
|
||||
### 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 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 operating the validator and their resume, while others might prefer anonymous validators with positive track records.
|
||||
|
||||
### What are the responsibilities 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 Ethermint can vote on proposals to change operational parameters (such as the block gas limit), coordinate upgrades, or make a decision on any given matter.
|
||||
|
||||
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.
|
||||
|
||||
### What does staking imply?
|
||||
|
||||
Staking Photons 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, Photons undergo a **3 weeks unbonding period** during which they are liable to being slashed for potential misbehavior committed by the validator before the unbonding process started.
|
||||
|
||||
Validators, and by association delegators, receive block rewards, fees, and have the right to participate in governance. If a validator misbehaves, a certain portion of their total stake is slashed. This means that every delegator that bonded Photons to this validator gets penalized in proportion to their bonded stake. Delegators are therefore incentivized to delegate to validators that they anticipate will function safely.
|
||||
|
||||
### Can a validator run away with their delegators' Photons?
|
||||
|
||||
By delegating to a validator, a user delegates voting power. The more voting power a validator have, the more weight they have in the consensus and governance processes. This does not mean that the validator has custody of their delegators' Photons. **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.
|
||||
|
||||
### How often will a validator be chosen to propose the next block? Does it go up with the quantity of bonded Photons?
|
||||
|
||||
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 proportional to the voting power (i.e. amount of bonded Photons) of the validator. For example, if the total bonded stake across all validators is 100 Photons and a validator's total stake is 10 Photons, then this validator will proposer ~10% of the blocks.
|
||||
|
||||
### Will validators of Ethermint ever be required to validate other zones in the Cosmos ecosystem?
|
||||
|
||||
Yes, they will. If governance decides so, validators of Ethermint may be required to validate additional zones in the Cosmos ecosystem.
|
||||
|
||||
## Incentives
|
||||
|
||||
### What is the incentive to stake?
|
||||
|
||||
Each member of a validator's staking pool earns different types of revenue:
|
||||
|
||||
- **Block rewards:** Native tokens of applications run by validators (e.g. Photons on Ethermint) 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.
|
||||
- **Transaction fees:** Ethermint maintains a whitelist of token that are accepted as fee payment. The initial fee token is the `atom`.
|
||||
|
||||
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. 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, they inherit the vote from their validator. This gives validators a major responsibility in the ecosystem.
|
||||
|
||||
### What are validators commission?
|
||||
|
||||
Revenue received by a validator's pool is split between the validator and their delegators. The validator can apply a commission on the part of the revenue that goes to their delegators. This commission is set as a percentage. Each validator is free to set their initial commission, maximum daily commission change rate and maximum commission. Ethermint enforces the parameter that each validator sets. Only the commission rate can change after the validator is created.
|
||||
|
||||
### How are block rewards distributed?
|
||||
|
||||
Block rewards are distributed proportionally to all validators relative to their voting power. This means that even though each validator gains atoms with each reward, all validators will maintain equal weight over time.
|
||||
|
||||
Let us take an example where we have 10 validators with equal voting power and a commission rate of 1%. Let us also assume that the reward for a block is 1000 Photons and that each validator has 20% of self-bonded Photons. These tokens do not go directly to the proposer. Instead, they are evenly spread among validators. So now each validator's pool has 100 Photons. These 100 Photons will be distributed according to each participant's stake:
|
||||
|
||||
- Commission: `100*80%*1% = 0.8 Photons`
|
||||
- Validator gets: `100\*20% + Commission = 20.8 Photons`
|
||||
- All delegators get: `100\*80% - Commission = 79.2 Photons`
|
||||
|
||||
Then, each delegator can claim their part of the 79.2 Photons in proportion to their stake in the validator's staking pool.
|
||||
|
||||
### 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 they propose if they include more than the strict minimum of required precommits.
|
||||
|
||||
When a validator is selected to propose the next block, they must include at least 2/3 precommits of the previous block. 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 rate and has 20% of self-delegated Photons. Now comes a successful block that collects a total of 1025.51020408 Photons in fees.
|
||||
|
||||
First, a 2% tax is applied. The corresponding Photons go to the reserve pool. Reserve pool's funds can be allocated through governance to fund bounties and upgrades.
|
||||
|
||||
- `2% * 1025.51020408 = 20.51020408` Photons go to the reserve pool.
|
||||
|
||||
1005 Photons 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 Photons
|
||||
- Commission: `105 * 80% * 1%` = 0.84 Photons
|
||||
- Validator's reward: `105 * 20% + Commission` = 21.84 Photons
|
||||
- Delegators' rewards: `105 * 80% - Commission` = 83.16 Photons (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 Photons
|
||||
- Commission: `100 * 80% * 1%` = 0.8 Photons
|
||||
- Validator's reward: `100 * 20% + Commission` = 20.8 Photons
|
||||
- Delegators' rewards: `100 * 80% - Commission` = 79.2 Photons (each delegator will be able to claim their portion of these rewards in proportion to their stake)
|
||||
|
||||
### What are the slashing conditions?
|
||||
|
||||
If a validator misbehaves, their delegated stake will be partially slashed. There are currently two faults that can result in slashing of funds for a validator and their 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, and if chain A and chain B share a common ancestor, then this validator will get slashed by 5% on chain A.
|
||||
- **Downtime:** If a validator misses more than 95% of the last 10.000 blocks, they will get slashed by 0.01%.
|
||||
|
||||
### Do validators need to self-delegate Photons?
|
||||
|
||||
Yes, they do need to self-delegate at least `1 atom`. Even though there is no obligation for validators to self-delegate more than `1 atom`, delegators should want their validator to have more self-delegated Photons 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-delegated Photons. If a validator's self-delegation 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. Ethermint will rely on the same effect initially. Other mechanisms are in place 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.
|
||||
- **UI warning:** Wallets can implement warnings that will be displayed to users 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
|
||||
|
||||
We do 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).
|
||||
37
docs/guides/validators/overview.md
Normal file
37
docs/guides/validators/overview.md
Normal file
@ -0,0 +1,37 @@
|
||||
<!--
|
||||
order: 1
|
||||
-->
|
||||
|
||||
# Overview
|
||||
|
||||
## Introduction
|
||||
|
||||
Ethermint is based on [Tendermint](https://github.com/tendermint/tendermint/tree/master/docs/introduction), 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 staking tokens (Photons) and have the tokens "delegated", or staked, to them by Photon holders. Ethermint will have 125 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 125 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
|
||||
|
||||
Validators should 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. 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 Discord. This is important since delegators will want to have information about the entity they are delegating their Photons 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 Forum](https://forum.cosmos.network/c/validating)
|
||||
61
docs/guides/validators/security.md
Normal file
61
docs/guides/validators/security.md
Normal file
@ -0,0 +1,61 @@
|
||||
<!--
|
||||
order: 3
|
||||
-->
|
||||
|
||||
# Validator Security
|
||||
|
||||
Learn about sentry nodes and HSMs to secure a validator {synopsis}
|
||||
|
||||
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 can be used with this yubikey [library](https://github.com/iqlusioninc/yubihsm.rs). 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)
|
||||
# Example ID: 3e16af0cead27979e1fc3dac57d03df3c7a77acc@3.87.179.235:26656
|
||||
|
||||
private_peer_ids = "node_ids_of_private_peers"
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
By default, uppercase environment variables with the following prefixes will replace lowercase command-line flags:
|
||||
|
||||
- `EM` (for Ethermint 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.
|
||||
240
docs/guides/validators/setup.md
Normal file
240
docs/guides/validators/setup.md
Normal file
@ -0,0 +1,240 @@
|
||||
<!--
|
||||
order: 2
|
||||
-->
|
||||
|
||||
# Run a Validator
|
||||
|
||||
Learn how to setup and run a validator node {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Validator Overview](./overview.md) {prereq}
|
||||
- [Full Node Setup](../localnet/single_node.md#manual-localnet) {prereq}
|
||||
|
||||
If you plan to use a KMS (key management system), you should go through these steps first: [Using a KMS](./../kms/kms.md).
|
||||
|
||||
## What is a Validator?
|
||||
|
||||
[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](./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](./security.md).
|
||||
:::
|
||||
|
||||
## Supported OS
|
||||
|
||||
We officially support macOS, Windows and Linux only. Other platforms may work but there is no
|
||||
guarantee. We will extend our support to other platforms after we have stabilized our current
|
||||
architecture.
|
||||
|
||||
## Minimum Requirements
|
||||
|
||||
To run testnet nodes, you will need a machine with the following minimum requirements:
|
||||
|
||||
<!-- TODO: verify -->
|
||||
- 4-core, x86_64 architecture processor;
|
||||
- 16 GB RAM;
|
||||
- 256 GB of storage space.
|
||||
|
||||
## Create Your Validator
|
||||
|
||||
Your `ethvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
|
||||
|
||||
```bash
|
||||
ethermintd tendermint show-validator
|
||||
```
|
||||
|
||||
To create your validator, just use the following command:
|
||||
|
||||
::: warning
|
||||
Don't use more `aphoton` than you have!
|
||||
:::
|
||||
|
||||
```bash
|
||||
ethermintd tx staking create-validator \
|
||||
--amount=1000000aphoton \
|
||||
--pubkey=$(ethermintd tendermint show-validator) \
|
||||
--moniker="choose a moniker" \
|
||||
--chain-id=<chain_id> \
|
||||
--commission-rate="0.10" \
|
||||
--commission-max-rate="0.20" \
|
||||
--commission-max-change-rate="0.01" \
|
||||
--min-self-delegation="1000000" \
|
||||
--gas="auto" \
|
||||
--gas-prices="0.025aphoton" \
|
||||
--from=<key_name>
|
||||
```
|
||||
|
||||
::: tip
|
||||
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
|
||||
`Min-self-delegation` is a strictly positive integer that represents the minimum amount of self-delegated voting power your validator must always have. A `min-self-delegation` of `1000000` means your validator will never have a self-delegation lower than `1atom`
|
||||
:::
|
||||
|
||||
You can confirm that you are in the validator set by using a third party explorer.
|
||||
|
||||
## Participate in Genesis as a Validator
|
||||
|
||||
::: warning
|
||||
The genesis ceremony for Ethermint mainnet is closed. Please skip to the next section.
|
||||
:::
|
||||
|
||||
If you want to participate in genesis as a validator, you need to justify that
|
||||
you have some stake at genesis, create one (or multiple) transactions to bond this stake to your validator address, and include this transaction in the genesis file.
|
||||
|
||||
Your `ethvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
|
||||
|
||||
```bash
|
||||
ethermintd tendermint show-validator
|
||||
```
|
||||
|
||||
Next, craft your `ethermintd gentx` command.
|
||||
|
||||
::: tip
|
||||
A `gentx` is a JSON file carrying a self-delegation. All genesis transactions are collected by a `genesis coordinator` and validated against an initial `genesis.json`.
|
||||
:::
|
||||
|
||||
::: warning Note
|
||||
Don't use more `aphoton` than you have!
|
||||
:::
|
||||
|
||||
```bash
|
||||
ethermintd gentx \
|
||||
--amount <amount_of_delegation_aphoton> \
|
||||
--commission-rate <commission_rate> \
|
||||
--commission-max-rate <commission_max_rate> \
|
||||
--commission-max-change-rate <commission_max_change_rate> \
|
||||
--pubkey <consensus_pubkey> \
|
||||
--name <key_name>
|
||||
```
|
||||
|
||||
::: tip
|
||||
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.
|
||||
:::
|
||||
|
||||
You can then submit your `gentx` on the [launch repository](https://github.com/cosmos/launch). These `gentx` will be used to form the final genesis file.
|
||||
|
||||
## 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. If a flag is not included in the command the field will default to empty (`--moniker` defaults to the machine name) if the field has never been set or remain the same if it has been set in the past.
|
||||
|
||||
The <key_name> specifies which validator you are editing. If you choose to not include certain flags, remember that the --from flag must be included to identify the validator to update.
|
||||
|
||||
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
|
||||
ethermintd tx staking edit-validator
|
||||
--moniker="choose a moniker" \
|
||||
--website="https://ethermint.dev" \
|
||||
--identity=6A0D65E29A4CBC8E \
|
||||
--details="To infinity and beyond!" \
|
||||
--chain-id=<chain_id> \
|
||||
--gas="auto" \
|
||||
--gas-prices="0.025aphoton" \
|
||||
--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
|
||||
ethermintd query staking 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
|
||||
ethermintd 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
|
||||
ethermintd 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
|
||||
ethermintd query tendermint-validator-set | grep "$(ethermintd tendermint show-address)"
|
||||
```
|
||||
|
||||
You should now see your validator in one of Ethermint explorers. You are looking for the `bech32` encoded `address` in the `~/.ethermintd/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.
|
||||
:::
|
||||
|
||||
## Halting Your Validator
|
||||
|
||||
When attempting to perform routine maintenance or planning for an upcoming coordinated
|
||||
upgrade, it can be useful to have your validator systematically and gracefully halt.
|
||||
You can achieve this by either setting the `halt-height` to the height at which
|
||||
you want your node to shutdown or by passing the `--halt-height` flag to `ethermintd`.
|
||||
The node will shutdown with a zero exit code at that given height after committing
|
||||
the block.
|
||||
|
||||
## Common Problems
|
||||
|
||||
### Problem #1: My validator has `voting_power: 0`
|
||||
|
||||
Your validator has become jailed. Validators get jailed, i.e. get removed from the active validator set, if they do not vote on `500` of the last `10000` blocks, or if they double sign.
|
||||
|
||||
If you got jailed for downtime, you can get your voting power back to your validator. First, if `ethermintd` is not running, start it up again:
|
||||
|
||||
```bash
|
||||
ethermintd start
|
||||
```
|
||||
|
||||
Wait for your full node to catch up to the latest block. Then, you can [unjail your validator](#unjail-validator)
|
||||
|
||||
Lastly, check your validator again to see if your voting power is back.
|
||||
|
||||
```bash
|
||||
ethermintd 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 node crashes because of `too many open files`
|
||||
|
||||
The default number of files Linux can open (per-process) is `1024`. `ethermintd` 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 `ethermintd start`. If you are using `systemd` or another process manager to launch `ethermintd` this may require some configuration at that level. A sample `systemd` file to fix this issue is below:
|
||||
|
||||
```toml
|
||||
# /etc/systemd/system/ethermintd.service
|
||||
[Unit]
|
||||
Description=Ethermint Node
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=ubuntu
|
||||
WorkingDirectory=/home/ubuntu
|
||||
ExecStart=/home/ubuntu/go/bin/ethermintd start
|
||||
Restart=on-failure
|
||||
RestartSec=3
|
||||
LimitNOFILE=4096
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
@ -40,12 +40,58 @@ You can also enable auto-completion with the `ethermintd completion` command. Fo
|
||||
|
||||
By default, your config and data are stored in the folder located at the `~/.ethermintd` directory.
|
||||
|
||||
:::warning
|
||||
Make sure you have backed up your wallet storage after creating the wallet or else your funds may be inaccessible in case of accident forever.
|
||||
:::
|
||||
```bash
|
||||
. # ~/.ethermintd
|
||||
├── data/ # Contains the databases used by the node.
|
||||
└── config/
|
||||
├── app.toml # Application-related configuration file.
|
||||
├── config.toml # Tendermint-related configuration file.
|
||||
├── genesis.json # The genesis file.
|
||||
├── node_key.json # Private key to use for node authentication in the p2p protocol.
|
||||
└── priv_validator_key.json # Private key to use as a validator in the consensus protocol.
|
||||
```
|
||||
|
||||
To specify the `ethermintd` config and data storage directory; you can update it using the global flag `--home <directory>`
|
||||
|
||||
### Configuring the Node
|
||||
|
||||
The Cosmos SDK automatically generates two configuration files inside `~/.ethermintd/config`:
|
||||
|
||||
- `config.toml`: used to configure the Tendermint, learn more on [Tendermint's documentation](https://docs.tendermint.com/master/nodes/configuration.html),
|
||||
- `app.toml`: generated by the Cosmos SDK, and used to configure your app, such as state pruning strategies, telemetry, gRPC and REST servers configuration, state sync, JSON-RPC, etc.
|
||||
|
||||
Both files are heavily commented, please refer to them directly to tweak your node.
|
||||
|
||||
One example config to tweak is the `minimum-gas-prices` field inside `app.toml`, which defines the minimum amount the validator node is willing to accept for processing a transaction. It is am anti spam mechanism and it will reject incoming transactions with less than the minimum gas prices.
|
||||
|
||||
If it's empty, make sure to edit the field with some value, for example `10token`, or else the node will halt on startup.
|
||||
|
||||
```toml
|
||||
# The minimum gas prices a validator is willing to accept for processing a
|
||||
# transaction. A transaction's fees must meet the minimum of any denomination
|
||||
# specified in this config (e.g. 0.25token1;0.0001token2).
|
||||
minimum-gas-prices = "0aphoton"
|
||||
```
|
||||
|
||||
### Pruning of State
|
||||
|
||||
There are four strategies for pruning state. These strategies apply only to state and do not apply to block storage.
|
||||
To set pruning, adjust the `pruning` parameter in the `~/.ethermintd/config/app.toml` file.
|
||||
The following pruning state settings are available:
|
||||
|
||||
- `everything`: Prune all saved states other than the current state.
|
||||
- `nothing`: Save all states and delete nothing.
|
||||
- `default`: Save the last 100 states and the state of every 10,000th block.
|
||||
- `custom`: Specify pruning settings with the `pruning-keep-recent`, `pruning-keep-every`, and `pruning-interval` parameters.
|
||||
|
||||
By default, every node is in `default` mode which is the recommended setting for most environments.
|
||||
If you would like to change your nodes pruning strategy then you must do so when the node is initialized. Passing a flag when starting `ethermint` will always override settings in the `app.toml` file, if you would like to change your node to the `everything` mode then you can pass the `---pruning everything` flag when you call `ethermintd start`.
|
||||
|
||||
::: warning
|
||||
**IMPORTANT**:
|
||||
When you are pruning state you will not be able to query the heights that are not in your store.
|
||||
:::
|
||||
|
||||
### Client configuration
|
||||
|
||||
We can view the default client config setting by using `ethermintd config` command:
|
||||
|
||||
@ -9,15 +9,11 @@ Configure and run an Ethermint node {synopsis}
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Installation](./installation.md) {prereq}
|
||||
|
||||
|
||||
## Configure the node daemon
|
||||
|
||||
Before kick-starting your node, we will have to configure your node so that it connects to the testnet:
|
||||
- [`ethermintd`](./binary.md) {prereq}
|
||||
|
||||
## Automated deployment
|
||||
|
||||
Run the local node
|
||||
Run the local node by running the `init.sh` script in the base directory of the repository.
|
||||
|
||||
::: warning
|
||||
The script below will remove any pre-existing binaries installed. Use the manual deploy if you want
|
||||
@ -31,14 +27,14 @@ to keep your binaries and configuration files.
|
||||
## Manual deployment
|
||||
|
||||
The instructions for setting up a brand new full node from scratch are the the same as running a
|
||||
[single node local testnet](./testnet.md#single-node-local-manual-testnet).
|
||||
[single node local testnet](./../guides/localnet/single_node.md#manual-localnet).
|
||||
|
||||
## Start node
|
||||
|
||||
To start your node, just type:
|
||||
|
||||
```bash
|
||||
ethermintd start --json-rpc.enable=true --json-rpc.api="eth,web3,net,txpool,debug"
|
||||
ethermintd start --json-rpc.enable=true --json-rpc.api="eth,web3,net"
|
||||
```
|
||||
|
||||
## Key Management
|
||||
@ -59,7 +55,7 @@ You can generate a new key/mnemonic with:
|
||||
ethermintd keys add $KEY
|
||||
```
|
||||
|
||||
To export your ethermint key as an ethereum private key (for use with Metamask for example):
|
||||
To export your ethermint key as an Ethereum private key (for use with [Metamask](./../guides/keys-wallets/metamask) for example):
|
||||
|
||||
```bash
|
||||
ethermintd keys unsafe-export-eth-key $KEY
|
||||
|
||||
@ -10,6 +10,3 @@ This section contains different client and API reference document.
|
||||
|
||||
1. [Join Testnet](./join)
|
||||
1. [Cloud Providers](./cloud_providers)
|
||||
1. [Testnet](./testnet)
|
||||
1. [Validator Setup](./validator-setup)
|
||||
1. [Security Checklist](./security)
|
||||
|
||||
@ -4,38 +4,102 @@ order: 1
|
||||
|
||||
# Joining a Testnet
|
||||
|
||||
This document outlines the steps to join an existing testnet
|
||||
This document outlines the steps to join an existing testnet {synopsis}
|
||||
|
||||
## Steps
|
||||
## Install `ethermintd`
|
||||
|
||||
1. [Install](./../quickstart/installation) the Ethermint binary `ethermintd`
|
||||
Follow the [installation](./../quickstart/installation) document to install the Ethermint binary `ethermintd`.
|
||||
|
||||
```bash
|
||||
go install https://github.com/tharsis/ethermint
|
||||
```
|
||||
:::warning
|
||||
Make sure you have the right version of `ethermintd` installed
|
||||
:::
|
||||
|
||||
2. Create an Ethermint [account](./../basics/accounts)
|
||||
## Initialize Node
|
||||
|
||||
```bash
|
||||
ethermintd keys add <keyname> --keyring-backend=test
|
||||
```
|
||||
We need to initialize the node to create all the necessary validator and node configuration files:
|
||||
|
||||
3. Copy genesis file
|
||||
```bash
|
||||
ethermintd init <your_custom_moniker>
|
||||
```
|
||||
|
||||
Follow this [link](https://gist.github.com/araskachoi/43f86f3edff23729b817e8b0bb86295a) and copy it over to the directory `~/.ethermintd/config/genesis.json`
|
||||
::: danger
|
||||
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
|
||||
:::
|
||||
|
||||
4. Add peers
|
||||
By default, the `init` command creates your `~/.ethermintd` directory with subfolders `config/` and `data/`.
|
||||
In the `config` directory, the most important files for configuration are `app.toml` and `config.toml`.
|
||||
|
||||
Edit the file located in `~/.ethermintd/config/config.toml` and the `persistent_peers` to the following:
|
||||
## Genesis & Seeds
|
||||
|
||||
```toml
|
||||
"05aa6587f07a0c6a9a8213f0138c4a76d476418a@18.204.206.179:26656,13d4a1c16d1f427988b7c499b6d150726aaf3aa0@3.86.104.251:26656,a00db749fa51e485c8376276d29d599258052f3e@54.210.246.165:26656"
|
||||
```
|
||||
### Copy the Genesis File
|
||||
|
||||
5. Validate genesis and start the Ethermint network
|
||||
Check the genesis file from the [`testnets`](https://github.com/tharsis/testnets) repository and copy it over to the `config` directory: `~/.ethermintd/config/genesis.json`.
|
||||
|
||||
```bash
|
||||
ethermintd validate-genesis
|
||||
Then verify the correctness of the genesis configuration file:
|
||||
|
||||
ethermintd start --pruning=nothing --rpc.unsafe --log_level "main:info,state:info,mempool:info"
|
||||
```
|
||||
```bash
|
||||
ethermintd validate-genesis
|
||||
```
|
||||
|
||||
### Add Seed Nodes
|
||||
|
||||
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.ethermintd/config/config.toml`. The [`testnets`](https://github.com/tharsis/testnets) repo contains links to some seed nodes.
|
||||
|
||||
Edit the file located in `~/.ethermintd/config/config.toml` and the `seeds` to the following:
|
||||
|
||||
```toml
|
||||
#######################################################
|
||||
### P2P Configuration Options ###
|
||||
#######################################################
|
||||
[p2p]
|
||||
|
||||
# ...
|
||||
|
||||
# Comma separated list of seed nodes to connect to
|
||||
seeds = ""
|
||||
```
|
||||
|
||||
:::tip
|
||||
For more information on seeds and peers, you can the Tendermint [P2P documentation](https://docs.tendermint.com/master/spec/p2p/peer.html).
|
||||
:::
|
||||
|
||||
### Start testnet
|
||||
|
||||
The final step is to [start the nodes](./../quickstart/run_node#start-node). Once enough voting power (+2/3) from the genesis validators is up-and-running, the testnet will start producing blocks.
|
||||
|
||||
```bash
|
||||
ethermintd start
|
||||
```
|
||||
|
||||
## Upgrading Your Node
|
||||
|
||||
> NOTE: These instructions are for full nodes that have ran on previous versions of and would like to upgrade to the latest testnet.
|
||||
|
||||
### Reset Data
|
||||
|
||||
:::warning
|
||||
If the version <new_version> you are upgrading to is not breaking from the previous one, you **should not** reset the data. If this is the case you can skip to [Restart](#restart)
|
||||
:::
|
||||
|
||||
First, remove the outdated files and reset the data.
|
||||
|
||||
```bash
|
||||
rm $HOME/.ethermintd/config/addrbook.json $HOME/.ethermintd/config/genesis.json
|
||||
ethermintd 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.
|
||||
:::
|
||||
|
||||
### Restart
|
||||
|
||||
To restart your node, just type:
|
||||
|
||||
```bash
|
||||
ethermintd start
|
||||
```
|
||||
|
||||
@ -1,59 +0,0 @@
|
||||
<!--
|
||||
order: 3
|
||||
-->
|
||||
|
||||
# Testnet
|
||||
|
||||
Learn how to deploy a local testnet or connect to an existing public one {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Install Ethermint](./installation) {prereq}
|
||||
|
||||
### Supported OS
|
||||
|
||||
We officially support macOS, Windows and Linux only. Other platforms may work but there is no
|
||||
guarantee. We will extend our support to other platforms after we have stabilized our current
|
||||
architecture.
|
||||
|
||||
### Minimum Requirements
|
||||
|
||||
To run testnet nodes, you will need a machine with the following minimum requirements:
|
||||
|
||||
- 4-core, x86_64 architecture processor;
|
||||
- 16 GB RAM;
|
||||
- 1 TB of storage space.
|
||||
|
||||
## Multi-node, Public, Manual Testnet
|
||||
|
||||
If you are looking to connect to a persistent public testnet. You will need to manually configure your node.
|
||||
|
||||
### Genesis and Seeds
|
||||
|
||||
#### Copy the Genesis File
|
||||
|
||||
::: tip
|
||||
If you want to start a network from scratch, you will need to start the [genesis procedure](#genesis-procedure) by creating a `genesis.json` and submit + collect the genesis transactions from the [validators](./validator-setup).
|
||||
:::
|
||||
|
||||
If you want to connect to an existing testnet, fetch the testnet's `genesis.json` file and copy it into the `ethermintd`'s config directory (i.e `$HOME/.ethermintd/config/genesis.json`).
|
||||
|
||||
Then verify the correctness of the genesis configuration file:
|
||||
|
||||
```bash
|
||||
ethermintd validate-genesis
|
||||
```
|
||||
|
||||
#### Add Seed Nodes
|
||||
|
||||
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.ethermintd/config/config.toml`. If those seeds aren't working, you can find more seeds and persistent peers on an existing explorer.
|
||||
|
||||
For more information on seeds and peers, you can the Tendermint [P2P documentation](https://docs.tendermint.com/master/spec/p2p/peer.html).
|
||||
|
||||
#### Start testnet
|
||||
|
||||
The final step is to [start the nodes](./../quickstart/run_node#start-node). Once enough voting power (+2/3) from the genesis validators is up-and-running, the testnet will start producing blocks.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn about how to setup a [validator](./validator-setup) node on Ethermint {hide}
|
||||
@ -1,124 +0,0 @@
|
||||
<!--
|
||||
order: 4
|
||||
-->
|
||||
|
||||
# Run a Validator
|
||||
|
||||
Configure a validator node to propose blocks and earn staking rewards {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Installation](./installation.md) {prereq}
|
||||
- [Run a Full Node](./run_node.md) {prereq}
|
||||
|
||||
## What is a Validator?
|
||||
|
||||
[Validators](https://hub.cosmos.network/master/validators/overview.html) 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](https://hub.cosmos.network/master/validators/validator-faq.html#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 `mainnet`, you should [research security](https://hub.cosmos.network/master/validators/security.html).
|
||||
:::
|
||||
|
||||
You may want to skip the next section if you have already set up a [full node](../emint-tutorials/join-mainnet.md).
|
||||
|
||||
## Create Your Validator
|
||||
|
||||
Your `cosmosvalconspub` consensus public key fron tendermint can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
|
||||
|
||||
```bash
|
||||
ethermintd tendermint show-validator
|
||||
```
|
||||
|
||||
To create your validator, just use the following command:
|
||||
|
||||
```bash
|
||||
ethermintd tx staking create-validator \
|
||||
--amount=1000000aphoton \
|
||||
--pubkey=$(ethermintd tendermint show-validator) \
|
||||
--moniker=<ethermint_validator> \
|
||||
--chain-id=<chain_id> \
|
||||
--commission-rate="0.10" \
|
||||
--commission-max-rate="0.20" \
|
||||
--commission-max-change-rate="0.01" \
|
||||
--min-self-delegation="1" \
|
||||
--gas="auto" \
|
||||
--gas-prices="0.025uatom" \
|
||||
--from=<key_name>
|
||||
```
|
||||
|
||||
::: tip
|
||||
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
|
||||
`Min-self-delegation` is a strictly positive integer that represents the minimum amount of self-delegated voting power your validator must always have. A `min-self-delegation` of 1 means your validator will never have a self-delegation lower than `1000000aphoton`
|
||||
:::
|
||||
|
||||
You can confirm that you are in the validator set by using a third party explorer.
|
||||
|
||||
## Genesis Transactions
|
||||
|
||||
A genesis transaction (aka `gentx`) is a JSON file carrying a self-delegation from a validator. All genesis transactions are collected by a genesis coordinator and validated against an initial `genesis.json` file.
|
||||
|
||||
A `gentx` does three things:
|
||||
|
||||
1. Makes the `validator` account you created into a validator operator account (i.e. the account that controls the validator).
|
||||
2. Self-delegates the provided `amount` of staking tokens.
|
||||
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `ethermintd init` command above.
|
||||
|
||||
If you want to participate in genesis as a validator, you need to justify that
|
||||
you have some stake at genesis, create one (or multiple) transactions to bond this stake to your validator address, and include this transaction in the genesis file.
|
||||
|
||||
Your `ethvalconspub`, as shown on the section above, can be used to create a validator transaction on genesis as well.
|
||||
|
||||
Next, craft your `ethermintd gentx` command:
|
||||
|
||||
::: tip
|
||||
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.
|
||||
:::
|
||||
|
||||
```bash
|
||||
ethermintd gentx \
|
||||
--amount <amount_of_delegation_uatom> \
|
||||
--commission-rate <commission_rate> \
|
||||
--commission-max-rate <commission_max_rate> \
|
||||
--commission-max-change-rate <commission_max_change_rate> \
|
||||
--pubkey $(ethermintd tendermint show-validator) \
|
||||
--name $KEY
|
||||
```
|
||||
|
||||
::: tip
|
||||
For more on `gentx`, use the help flag: `ethermintd gentx -h`
|
||||
:::
|
||||
|
||||
## Confirm Your Validator is Running
|
||||
|
||||
Your validator is active if the following command returns anything:
|
||||
|
||||
```bash
|
||||
ethermintd query tendermint-validator-set | grep "$(ethermintd tendermint show-validator)"
|
||||
```
|
||||
|
||||
You should now see your validator in one of the block explorers. You are looking for the `bech32`
|
||||
encoded `address` in the `~/.ethermintd/config/priv_validator.json` file.
|
||||
|
||||
::: tip
|
||||
To be in the validator set, you need to have more total voting power than the 100th validator.
|
||||
:::
|
||||
|
||||
## Halt Your Validator Node
|
||||
|
||||
When attempting to perform routine maintenance or planning for an upcoming coordinated
|
||||
upgrade, it can be useful to have your validator systematically and gracefully halt the chain and shutdown the node.
|
||||
|
||||
You can achieve this by setting one of the following flags during when using the `ethermintd start` command:
|
||||
|
||||
- `--halt-height`: to the block height at which to shutdown the node
|
||||
- `--halt-time`: to the minimum block time (in Unix seconds) at which to shutdown the node
|
||||
|
||||
The node will stop processing blocks with a zero exit code at that given height/time after
|
||||
committing the block.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Start and connect a [client](./clients.md) to a running network {hide}
|
||||
Loading…
Reference in New Issue
Block a user