diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 90afae35..06c67df1 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -1,11 +1,11 @@ # Updating the docs -If you want to open a PR on the Cosmos SDK to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/tharsis/ethermint/tree/master/CONTRIBUTING.md#updating-documentation) +If you want to open a PR on the Cosmos SDK to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/tharsis/ethermint/tree/main/CONTRIBUTING.md#updating-documentation) ## Translating - Docs translations live in a `docs/country-code/` folder, where `country-code` stands for the country code of the language used (`cn` for Chinese, `kr` for Korea, `fr` for France, ...). -- Always translate content living on `master`. +- Always translate content living on `main`. - Only content under `/docs/intro/`, `/docs/basics/`, `/docs/core/`, `/docs/building-modules/` and `docs/interfaces` needs to be translated, as well as `docs/README.md`. It is also nice (but not mandatory) to translate `/docs/spec/`. - Specify the release/tag of the translation in the README of your translation folder. Update the release/tag each time you update the translation. @@ -14,12 +14,12 @@ If you want to open a PR on the Cosmos SDK to update the documentation, please f The documentation for Ethermint is hosted at https://ethermint.dev/ built from the files in this (`/docs`) directory for -[master](https://github.com/tharsis/ethermint/tree/master/docs). +[master](https://github.com/tharsis/ethermint/tree/main/docs). ### How It Works There is a CircleCI job listening for changes in the `/docs` directory, on -the `master` branch. Any updates to files in this directory +the `main` branch. Any updates to files in this directory on that branch will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo. @@ -90,7 +90,7 @@ To build documentation as a static website run `yarn run build`. You will find t ## Search -We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs. +We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/main/configs/cosmos_network.json) configuration file that we can update with PRs. ### Update and Build the RPC docs diff --git a/docs/guides/README.md b/docs/guides/README.md index e16f8695..727e0dcd 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -6,11 +6,14 @@ parent: # Guides -This section contains different guides to use wallets and popular Ethereum tools with Ethermint. - -1. [Single Node Localnet](./localnet/single_node) -1. [Multi Node Localnet](./localnet/multi_node) -1. [Keyring](./keys-wallets/keyring) -1. [Metamask](./keys-wallets/metamask) -1. [Truffle](./tools/truffle) -1. [Remix](./tools/remix) +1. Localnet + * [Single Node Localnet](./localnet/single_node) + * [Multi Node Localnet](./localnet/multi_node) +2. Keys and Wallets + * [Keyring](./keys-wallets/keyring) + * [Metamask](./keys-wallets/metamask) +3. Ethereum Tooling + * [Truffle](./tools/truffle) + * [Remix](./tools/remix) +4. [Validators](./validators/overview) +5. [Key Management System](./kms/kms) diff --git a/docs/guides/validators/faq.md b/docs/guides/validators/faq.md index a6381052..99a5f67d 100644 --- a/docs/guides/validators/faq.md +++ b/docs/guides/validators/faq.md @@ -12,7 +12,7 @@ Ethermint is based on [Tendermint](https://tendermint.com/docs/introduction/what ### 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. +Ethermint is a public Proof-of-Stake (PoS) blockchain, meaning that the weight of validators is determined by the amount of staking tokens bonded as collateral. The **Photon** is Ethermint's native token. Photons can be self-delegated directly by the validator or delegated to them by other Photon 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. @@ -26,11 +26,11 @@ Of course, it is possible and encouraged for users to run full-nodes even if the ### 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). +Delegators are Photon holders who cannot, or do not want to run a validator themselves. Photon 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). +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 Cosmos Hub's [delegator's faq](https://hub.cosmos.network/main/delegators/delegator-faq.html). ## Becoming a Validator @@ -48,9 +48,9 @@ Any participant in the network can signal that they want to become a validator b - **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. +Once a validator is created, Photon holders can delegate Photons 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. +Out of all validator candidates that signaled themselves, the 125 with the most total stake are the ones who are designated as 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 @@ -86,7 +86,7 @@ Self-delegation is delegation from a validator to themselves. This amount can be ### Is there a minimum amount of Photons that must be delegated to be an active (=bonded) validator? -The minimum is `1 aphoton`. +The minimum is `1 photon`. ### How will delegators choose their validators? @@ -109,7 +109,7 @@ No, they do not. Each delegator will value validators based on their own criteri 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. +- **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. @@ -146,8 +146,8 @@ Yes, they will. If governance decides so, validators of Ethermint may be require 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`. +- **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 Photon holders to bond their stake, as non-bonded Photon 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 `photon`. 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. @@ -211,7 +211,7 @@ If a validator misbehaves, their delegated stake will be partially slashed. Ther ### 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. +Yes, they do need to self-delegate at least `1 photon`. Even though there is no obligation for validators to self-delegate more than `1 photon`, 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. diff --git a/docs/guides/validators/overview.md b/docs/guides/validators/overview.md index f782bbca..e8015a9c 100644 --- a/docs/guides/validators/overview.md +++ b/docs/guides/validators/overview.md @@ -6,11 +6,11 @@ order: 1 ## 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. +Ethermint is based on [Tendermint](https://github.com/tendermint/tendermint/blob/master/docs/introduction/what-is-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 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. +Validator candidates can bond their own staking tokens and have the tokens "delegated", or staked, to them by token holders. The **Photon** is Ethermint's native token. At its onset, Ethermint will launch with 125 validators; 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 Ethermint 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. +Validators and their delegators will earn Photons as block provisions and tokens as transaction fees through execution of the Tendermint consensus protocol. Initially, transaction fees will be paid in Photons 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. @@ -20,7 +20,7 @@ Validators should set up a physical operation secured with restricted access. A 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. +We anticipate that network requirements will be low initially. 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 @@ -28,7 +28,7 @@ Set up a dedicated validator's website and signal your intention to become a val ## Seek Legal Advice -Seek legal advice if you intend to run a Validator. +Seek legal advice if you intend to run a validator. ## Community diff --git a/docs/guides/validators/setup.md b/docs/guides/validators/setup.md index c03d71d9..44800b38 100644 --- a/docs/guides/validators/setup.md +++ b/docs/guides/validators/setup.md @@ -11,11 +11,11 @@ Learn how to setup and run a validator node {synopsis} - [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). +If you plan to use a Key Management System (KMS), 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. +[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). @@ -70,17 +70,13 @@ When specifying commission parameters, the `commission-max-change-rate` is used ::: ::: 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` +`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 `1 aphoton` ::: 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.