certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge PR #4388: Remove gaia docs from sdk repo

This commit is contained in:
gamarin2 2019-05-21 20:16:55 +02:00 committed by Alexander Bezobchuk
parent 3a2423d298
commit 995aea853c
32 changed files with 8 additions and 4294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@ -20,14 +20,6 @@ breaking changes.
**Note**: Requires [Go 1.12+](https://golang.org/dl/)
## Cosmos Hub Mainnet
To run a full-node for the mainnet of the Cosmos Hub, first [install `gaia`](./docs/cosmos-hub/installation.md), then follow [the guide](./docs/cosmos-hub/join-mainnet.md).
For status updates and genesis file, see the
[launch repo](https://github.com/cosmos/launch).
## Quick Start
To learn how the SDK works from a high-level perspective, go to the [SDK Intro](./docs/intro/README.md).
@ -36,6 +28,10 @@ If you want to get started quickly and learn how to build on top of the SDK, ple
For more, please go to the [Cosmos SDK Docs](./docs/README.md)
## Cosmos Hub Mainnet
The Cosmos Hub application, `gaia`, has moved to its [own repository](https://github.com/cosmos/gaia). Go there to join the Cosmos Hub mainnet and more.
## Disambiguation
This Cosmos-SDK project is not related to the [React-Cosmos](https://github.com/react-cosmos/react-cosmos) project (yet). Many thanks to Evan Coury and Ovidiu (@skidding) for this Github organization name. As per our agreement, this disambiguation notice will stay here.

20
docs/.vuepress/config.js
View File

@ -33,26 +33,6 @@ module.exports = {
"/intro/ocap"
]
},
{
title: "Cosmos Hub",
collapsable: true,
children: [
"/cosmos-hub/what-is-gaia",
"/cosmos-hub/installation",
"/cosmos-hub/join-mainnet",
"/cosmos-hub/validators/validator-setup",
"/cosmos-hub/validators/overview",
"/cosmos-hub/validators/security",
"/cosmos-hub/validators/validator-faq",
"/cosmos-hub/delegator-guide-cli",
"/cosmos-hub/genesis",
"/cosmos-hub/hd-wallets",
"/cosmos-hub/ledger",
"/cosmos-hub/gaiacli",
"/cosmos-hub/join-testnet",
"/cosmos-hub/deploy-testnet"
]
},
{
title: "Tutorial",
collapsable: true,

10
docs/README.md
View File

@ -11,12 +11,6 @@
- [SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk): Godocs of the Cosmos SDK.
- [REST API spec](https://cosmos.network/rpc/): List of endpoints to interact with a `gaia` full-node through REST.
## Cosmos Hub
- [Join the mainnet](./cosmos-hub/join-mainnet.md) of the Cosmos Hub.
- [Join the latest public testnet](./cosmos-hub/join-testnet.md) of the Cosmos Hub.
- [Start your own `gaia` testnet](./cosmos-hub/deploy-testnet.md).
## Creating a new SDK project
To create a new project, you can either:
@ -24,6 +18,10 @@ To create a new project, you can either:
- Fork [this repo](https://github.com/cosmos/sdk-application-tutorial/). Do not forget to remove the `nameservice` module from the various files if you don't need it.
- Use community tools like [chainkit](https://github.com/blocklayerhq/chainkit).
## Cosmos Hub
The Cosmos Hub (`gaia`) docs have moved [here](https://github.com/cosmos/gaia/tree/master/docs).
## Languages
The Cosmos-SDK is currently written in [Golang](https://golang.org/), though the

23
docs/cosmos-hub/README.md
View File

@ -1,23 +0,0 @@
# Cosmos Hub Documentation
Welcome to the documentation of the **Cosmos Hub application: `gaia`**.
## Join the Cosmos Hub Mainnet
- [Install the `gaia` application](./installation.md)
- [Set up a full node and join the mainnet](./join-mainnet.md)
- [Upgrade to a validator node](./validators/validator-setup.md)
## Join the Cosmos Hub Public Testnet
- [Join the testnet](./join-testnet.md)
## Setup Your Own `gaia` Testnet
- [Setup your own `gaia` testnet](./deploy-testnet.md)
## Additional Resources
- [Intro to validators](./validators/overview.md)
- [Validator FAQ](./validators/validator-faq.md)
- [Validator security considerations](./validators/security.md)

523
docs/cosmos-hub/delegator-guide-cli.md
View File

@ -1,523 +0,0 @@
# Delegator Guide (CLI)
This document contains all the necessary information for delegators to interact with the Cosmos Hub through the Command-Line Interface (CLI).
It also contains instructions on how to manage accounts, restore accounts from the fundraiser and use a ledger nano device.
::: danger
**Very Important**: Please assure that you follow the steps described hereinafter
carefully, as negligence in this significant process could lead to an indefinite
loss of your Atoms. Therefore, read through the following instructions in their
entirety prior to proceeding and reach out to us in case you need support.
Please also note that you are about to interact with the Cosmos Hub, a
blockchain technology containing highly experimental software. While the
blockchain has been developed in accordance to the state of the art and audited
with utmost care, we can nevertheless expect to have issues, updates and bugs.
Furthermore, interaction with blockchain technology requires
advanced technical skills and always entails risks that are outside our control.
By using the software, you confirm that you understand the inherent risks
associated with cryptographic software (see also risk section of the
[Interchain Cosmos Contribution terms](https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf)) and that the Interchain Foundation and/or
the Tendermint Team may not be held liable for potential damages arising out of the use of the
software. Any use of this open source software released under the Apache 2.0 license is
done at your own risk and on a "AS IS" basis, without warranties or conditions
of any kind.
:::
Please exercise extreme caution!
## Table of Contents
- [Installing `gaiacli`](#installing-gaiacli)
- [Cosmos Accounts](#cosmos-accounts)
+ [Restoring an Account from the Fundraiser](#restoring-an-account-from-the-fundraiser)
+ [Creating an Account](#creating-an-account)
- [Accessing the Cosmos Hub Network](#accessing-the-cosmos-hub-network)
+ [Running Your Own Full-Node](#running-your-own-full-node)
+ [Connecting to a Remote Full-Node](#connecting-to-a-remote-full-node)
- [Setting Up `gaiacli`](#setting-up-gaiacli)
- [Querying the State](#querying-the-state)
- [Sending Transactions](#sending-transactions)
+ [A Note on Gas and Fees](#a-note-on-gas-and-fees)
+ [Bonding Atoms and Withdrawing Rewards](#bonding-atoms-and-withdrawing-rewards)
+ [Participating in Governance](#participating-in-governance)
+ [Signing Transactions from an Offline Computer](#signing-transactions-from-an-offline-computer)
## Installing `gaiacli`
`gaiacli`: This is the command-line interface to interact with a `gaiad` full-node.
::: warning
**Please check that you download the latest stable release of `gaiacli` that is available**
:::
[**Download the binaries**]
Not available yet.
[**Install from source**](https://cosmos.network/docs/cosmos-hub/installation.html)
::: tip
`gaiacli` is used from a terminal. To open the terminal, follow these steps:
- **Windows**: `Start` > `All Programs` > `Accessories` > `Command Prompt`
- **MacOS**: `Finder` > `Applications` > `Utilities` > `Terminal`
- **Linux**: `Ctrl` + `Alt` + `T`
:::
## Cosmos Accounts
At the core of every Cosmos account, there is a seed, which takes the form of a 12 or 24-words mnemonic. From this mnemonic, it is possible to create any number of Cosmos accounts, i.e. pairs of private key/public key. This is called an HD wallet (see [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) for more information on the HD wallet specification).
```
Account 0 Account 1 Account 2
+------------------+ +------------------+ +------------------+
| | | | | |
| Address 0 | | Address 1 | | Address 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Public key 0 | | Public key 1 | | Public key 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Private key 0 | | Private key 1 | | Private key 2 |
| ^ | | ^ | | ^ |
+------------------+ +------------------+ +------------------+
| | |
| | |
| | |
+--------------------------------------------------------------------+
|
|
+---------+---------+
| |
| Mnemonic (Seed) |
| |
+-------------------+
```
The funds stored in an account are controlled by the private key. This private key is generated using a one-way function from the mnemonic. If you lose the private key, you can retrieve it using the mnemonic. However, if you lose the mnemonic, you will lose access to all the derived private keys. Likewise, if someone gains access to your mnemonic, they gain access to all the associated accounts.
::: danger
**Do not lose or share your 12 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.**
:::
The address is a public string with a human-readable prefix (e.g. `cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg`) that identifies your account. When someone wants to send you funds, they send it to your address. It is computationally infeasible to find the private key associated with a given address.
### Restoring an Account from the Fundraiser
::: tip
*NOTE: This section only concerns fundraiser participants*
:::
If you participated in the fundraiser, you should be in possession of a 12-words mnemonic. Newly generated mnemonics use 24 words, but 12-word mnemonics are also compatible with all the Cosmos tools.
#### On a Ledger Device
At the core of a ledger device, there is a mnemonic used to generate accounts on multiple blockchains (including the Cosmos Hub). Usually, you will create a new mnemonic when you initialize your ledger device. However, it is possible to tell the ledger device to use a mnemonic provided by the user instead. Let us go ahead and see how you can input the mnemonic you obtained during the fundraiser as the seed of your ledger device.
::: warning
*NOTE: To do this, **it is preferable to use a brand new ledger device.**. Indeed, there can be only one mnemonic per ledger device. If, however, you want to use a ledger that is already initialized with a seed, you can reset it by going in `Settings`>`Device`>`Reset All`. **Please note that this will wipe out the seed currently stored on the device. If you have not properly secured the associated mnemonic, you could lose your funds!!!***
:::
The following steps need to be performed on an un-initialized ledger device:
1. Connect your ledger device to the computer via USB
2. Press both buttons
3. Do **NOT** choose the "Config as a new device" option. Instead, choose "Restore Configuration"
4. Choose a PIN
5. Choose the 12 words option
6. Input each of the words you got during the fundraiser, in the correct order.
Your ledger is now correctly set up with your fundraiser mnemonic! Do not lose this mnemonic! If your ledger is compromised, you can always restore a new device again using the same mnemonic.
Next, click [here](#using-a-ledger-device) to learn how to generate an account.
#### On a Computer
::: warning
**NOTE: It is more secure to perform this action on an offline computer**
:::
To restore an account using a fundraiser mnemonic and store the associated encrypted private key on a computer, use the following command:
```bash
gaiacli keys add <yourKeyName> --recover
```
You will be prompted to input a passphrase that is used to encrypt the private key of account `0` on disk. Each time you want to send a transaction, this password will be required. If you lose the password, you can always recover the private key with the mnemonic.
- `<yourKeyName>` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
- You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated.
### Creating an Account
To create an account, you just need to have `gaiacli` installed. Before creating it, you need to know where you intend to store and interact with your private keys. The best options are to store them in an offline dedicated computer or a ledger device. Storing them on your regular online computer involves more risk, since anyone who infiltrates your computer through the internet could exfiltrate your private keys and steal your funds.
#### Using a Ledger Device
::: warning
**Only use Ledger devices that you bought factory new or trust fully**
:::
When you initialize your ledger, a 24-word mnemonic is generated and stored in the device. This mnemonic is compatible with Cosmos and Cosmos accounts can be derived from it. Therefore, all you have to do is make your ledger compatible with `gaiacli`. To do so, you need to go through the following steps:
1. Download the Ledger Live app [here](https://www.ledger.com/pages/ledger-live).
2. Connect your ledger via USB and update to the latest firmware
3. Go to the ledger live app store, and download the "Cosmos" application (this can take a while). **Note: You may have to enable `Dev Mode` in the `Settings` of Ledger Live to be able to download the "Cosmos" application**.
4. Navigate to the Cosmos app on your ledger device
Then, to create an account, use the following command:
```bash
gaiacli keys add <yourAccountName> --ledger
```
::: warning
**This command will only work while the Ledger is plugged in and unlocked**
:::
- `<yourKeyName>` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
- You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated.
#### Using a Computer
::: warning
**NOTE: It is more secure to perform this action on an offline computer**
:::
To generate an account, just use the following command:
```bash
gaiacli keys add <yourKeyName>
```
The command will generate a 24-words mnemonic and save the private and public keys for account `0` at the same time. You will be prompted to input a passphrase that is used to encrypt the private key of account `0` on disk. Each time you want to send a transaction, this password will be required. If you lose the password, you can always recover the private key with the mnemonic.
::: danger
**Do not lose or share your 12 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.**
:::
::: warning
After you have secured your mnemonic (triple check!), you can delete bash history to ensure no one can retrieve it:
```bash
history -c
rm ~/.bash_history
```
:::
- `<yourKeyName>` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
- You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated.
You can generate more accounts from the same mnemonic using the following command:
```bash
gaiacli keys add <yourKeyName> --recover --account 1
```
This command will prompt you to input a passphrase as well as your mnemonic. Change the account number to generate a different account.
## Accessing the Cosmos Hub Network
In order to query the state and send transactions, you need a way to access the network. To do so, you can either run your own full-node, or connect to someone else's.
::: danger
**NOTE: Do not share your mnemonic (12 or 24 words) with anyone. The only person who should ever need to know it is you. This is especially important if you are ever approached via email or direct message by someone requesting that you share your mnemonic for any kind of blockchain services or support. No one from Cosmos, the Tendermint team or the Interchain Foundation will ever send an email that asks for you to share any kind of account credentials or your mnemonic."**.
:::
### Running Your Own Full-Node
This is the most secure option, but comes with relatively high resource requirements. In order to run your own full-node, you need good bandwidth and at least 1TB of disk space.
You will find the tutorial on how to install `gaiad` [here](https://cosmos.network/docs/cosmos-hub/installation.html), and the guide to run a full-node [here](https://cosmos.network/docs/cosmos-hub/join-mainnet.html).
### Connecting to a Remote Full-Node
If you do not want or cannot run your own node, you can connect to someone else's full-node. You should pick an operator you trust, because a malicious operator could return incorrect query results or censor your transactions. However, they will never be able to steal your funds, as your private keys are stored locally on your computer or ledger device. Possible options of full-node operators include validators, wallet providers or exchanges.
In order to connect to the full-node, you will need an address of the following form: `https://77.87.106.33:26657` (*Note: This is a placeholder*). This address has to be communicated by the full-node operator you choose to trust. You will use this address in the [following section](#setting-up-gaiacli).
## Setting Up `gaiacli`
::: tip
**Before setting up `gaiacli`, make sure you have set up a way to [access the Cosmos Hub network](#accessing-the-cosmos-hub-network)**
:::
::: warning
**Please check that you are always using the latest stable release of `gaiacli`**
:::
`gaiacli` is the tool that enables you to interact with the node that runs on the Cosmos Hub network, whether you run it yourself or not. Let us set it up properly.
In order to set up `gaiacli`, use the following command:
```bash
gaiacli config <flag> <value>
```
It allows you to set a default value for each given flag.
First, set up the address of the full-node you want to connect to:
```bash
gaiacli config node <host>:<port
// example: gaiacli config node https://77.87.106.33:26657
```
If you run your own full-node, just use `tcp://localhost:26657` as the address.
Then, let us set the default value of the `--trust-node` flag:
```bash
gaiacli config trust-node false
// Set to true if you run a light-client node, false otherwise
```
Finally, let us set the `chain-id` of the blockchain we want to interact with:
```bash
gaiacli config chain-id cosmoshub-2
```
## Querying the State
::: tip
**Before you can bond atoms and withdraw rewards, you need to [set up `gaiacli`](#setting-up-gaiacli)**
:::
`gaiacli` lets you query all relevant information from the blockchain, like account balances, amount of bonded tokens, outstanding rewards, governance proposals and more. Next is a list of the most useful commands for delegator.
```bash
// query account balances and other account-related information
gaiacli query account <yourAddress>
// query the list of validators
gaiacli query staking validators
// query the information of a validator given their address (e.g. cosmosvaloper1n5pepvmgsfd3p2tqqgvt505jvymmstf6s9gw27)
gaiacli query staking validator <validatorAddress>
// query all delegations made from a delegator given their address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg)
gaiacli query staking delegations <delegatorAddress>
// query a specific delegation made from a delegator (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) to a validator (e.g. cosmosvaloper1n5pepvmgsfd3p2tqqgvt505jvymmstf6s9gw27) given their addresses
gaiacli query staking delegation <delegatorAddress> <validatorAddress>
// query the rewards of a delegator given a delegator address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg)
gaiacli query distr rewards <delegatorAddress>
// query all proposals currently open for depositing
gaiacli query gov proposals --status deposit_period
// query all proposals currently open for voting
gaiacli query gov proposals --status voting_period
// query a proposal given its proposalID
gaiacli query gov proposal <proposalID>
```
For more commands, just type:
```bash
gaiacli query
```
For each command, you can use the `-h` or `--help` flag to get more information.
## Sending Transactions
::: warning
On Cosmos Hub mainnet, the accepted denom is `uatom`, where `1atom = 1,000,000uatom`
:::
### A Note on Gas and Fees
Transactions on the Cosmos Hub network need to include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. The formula is the following:
```
fees = ceil(gas * gasPrices)
```
The `gas` is dependent on the transaction. Different transaction require different amount of `gas`. The `gas` amount for a transaction is calculated as it is being processed, but there is a way to estimate it beforehand by using the `auto` value for the `gas` flag. Of course, this only gives an estimate. You can adjust this estimate with the flag `--gas-adjustment` (default `1.0`) if you want to be sure you provide enough `gas` for the transaction. For the remainder of this tutorial, we will use a `--gas-adjustment` of `1.5`.
The `gasPrice` is the price of each unit of `gas`. Each validator sets a `min-gas-price` value, and will only include transactions that have a `gasPrice` greater than their `min-gas-price`.
The transaction `fees` are the product of `gas` and `gasPrice`. As a user, you have to input 2 out of 3. The higher the `gasPrice`/`fees`, the higher the chance that your transaction will get included in a block.
::: tip
For mainnet, the recommended `gas-prices` is `0.025uatom`.
:::
### Sending Tokens
::: tip
**Before you can bond atoms and withdraw rewards, you need to [set up `gaiacli`](#setting-up-gaiacli) and [create an account](#creating-an-account)**
:::
::: warning
**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a Ledger Nano S device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).**
:::
```bash
// Send a certain amount of tokens to an address
// Ex value for parameters (do not actually use these values in your tx!!): <to_address>=cosmos16m93fezfiezhvnjajzrfyszml8qm92a0w67ntjhd3d0 <amount>=1000000uatom
// Ex value for flags: <gasPrice>=0.025uatom
gaiacli tx send <to_address> <amount> --from <yourKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
```
### Bonding Atoms and Withdrawing Rewards
::: tip
**Before you can bond atoms and withdraw rewards, you need to [set up `gaiacli`](#setting-up-gaiacli) and [create an account](#creating-an-account)**
:::
::: warning
**Before bonding Atoms, please read the [delegator faq](https://cosmos.network/resources/delegators) to understand the risk and responsibilities involved with delegating**
:::
::: warning
**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).**
:::
```bash
// Bond a certain amount of Atoms to a given validator
// ex value for flags: <validatorAddress>=cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, <amountToBound>=10000000uatom, <gasPrice>=0.025uatom
gaiacli tx staking delegate <validatorAddress> <amountToBond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
// Redelegate a certain amount of Atoms from a validator to another
// Can only be used if already bonded to a validator
// Redelegation takes effect immediately, there is no waiting period to redelegate
// After a redelegation, no other redelegation can be made from the account for the next 3 weeks
// ex value for flags: <stcValidatorAddress>=cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, <amountToRedelegate>=100000000uatom, <gasPrice>=0.025uatom
gaiacli tx staking redelegate <srcValidatorAddress> <destValidatorAddress> <amountToRedelegate> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
// Withdraw all rewards
// ex value for flag: <gasPrice>=0.025uatom
gaiacli tx distr withdraw-all-rewards --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
// Unbond a certain amount of Atoms from a given validator
// You will have to wait 3 weeks before your Atoms are fully unbonded and transferrable
// ex value for flags: <validatorAddress>=cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, <amountToUnbound>=10000000uatom, <gasPrice>=0.025uatom
gaiacli tx staking unbond <validatorAddress> <amountToUnbond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
```
::: warning
**If you use a connected Ledger, you will be asked to confirm the transaction on the device before it is signed and broadcast to the network. Note that the command will only work while the Ledger is plugged in and unlocked.**
:::
To confirm that your transaction went through, you can use the following queries:
```bash
// your balance should change after you bond Atoms or withdraw rewards
gaiacli query account
// you should have delegations after you bond Atom
gaiacli query staking delegations <delegatorAddress>
// this returns your tx if it has been included
// use the tx hash that was displayed when you created the tx
gaiacli query tx <txHash>
```
Double check with a block explorer if you interact with the network through a trusted full-node.
## Participating in Governance
#### Primer on Governance
The Cosmos Hub has a built-in governance system that lets bonded Atom holders vote on proposals. There are three types of proposal:
- `Text Proposals`: These are the most basic type of proposals. They can be used to get the opinion of the network on a given topic.
- `Parameter Proposals`: These are used to update the value of an existing parameter.
- `Software Upgrade Proposal`: These are used to propose an upgrade of the Hub's software.
Any Atom holder can submit a proposal. In order for the proposal to be open for voting, it needs to come with a `deposit` that is greater than a parameter called `minDeposit`. The `deposit` need not be provided in its entirety by the submitter. If the initial proposer's `deposit` is not sufficient, the proposal enters the `deposit_period` status. Then, any Atom holder can increase the deposit by sending a `depositTx`.
Once the `deposit` reaches `minDeposit`, the proposal enters the `voting_period`, which lasts 2 weeks. Any **bonded** Atom holder can then cast a vote on this proposal. The options are `Yes`, `No`, `NoWithVeto` and `Abstain`. The weight of the vote is based on the amount of bonded Atoms of the sender. If they don't vote, delegator inherit the vote of their validator. However, delegators can override their validator's vote by sending a vote themselves.
At the end of the voting period, the proposal is accepted if there are more than 50% `Yes` votes (excluding `Abstain ` votes) and less than 33.33% of `NoWithVeto` votes (excluding `Abstain` votes).
#### In Practice
::: tip
**Before you can bond atoms and withdraw rewards, you need to [bond Atoms](#bonding-atoms-and-withdrawing-rewards)**
:::
::: warning
**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).**
:::
```bash
// Submit a Proposal
// <type>=text/parameter_change/software_upgrade
// ex value for flag: <gasPrice>=0.025uatom
gaiacli tx gov submit-proposal --title "Test Proposal" --description "My awesome proposal" --type <type> --deposit=10000000uatom --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>
// Increase deposit of a proposal
// Retrieve proposalID from $gaiacli query gov proposals --status deposit_period
// ex value for parameter: <deposit>=10000000uatom
gaiacli tx gov deposit <proposalID> <deposit> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>
// Vote on a proposal
// Retrieve proposalID from $gaiacli query gov proposals --status voting_period
// <option>=yes/no/no_with_veto/abstain
gaiacli tx gov vote <proposalID> <option> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>
```
### Signing Transactions From an Offline Computer
If you do not have a ledger device and want to interact with your private key on an offline computer, you can use the following procedure. First, generate an unsigned transaction on an **online computer** with the following command (example with a bonding transaction):
```bash
// Bond Atoms
// ex value for flags: <amountToBound>=10000000uatom, <bech32AddressOfValidator>=cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, <gasPrice>=0.025uatom, <delegatorAddress>=cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg
gaiacli tx staking delegate <validatorAddress> <amountToBond> --from <delegatorAddress> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --generate-only > unsignedTX.json
```
In order to sign, you will also need the `chain-id`, `account-number` and `sequence`. The `chain-id` is a unique identifier for the blockchain on which you are submitting the transaction. The `account-number` is an identifier generated when your account first receives funds. The `sequence` number is used to keep track of the number of transactions you have sent and prevent replay attacks.
Get the chain-id from the genesis file (`cosmoshub-2`), and the two other fields using the account query:
```bash
gaiacli query account <yourAddress> --chain-id cosmoshub-2
```
Then, copy `unsignedTx.json` and transfer it (e.g. via USB) to the offline computer. If it is not done already, [create an account on the offline computer](#using-a-computer). For additional security, you can double check the parameters of your transaction before signing it using the following command:
```bash
cat unsignedTx.json
```
Now, sign the transaction using the following command. You will need the `chain-id`, `sequence` and `account-number` obtained earlier:
```bash
gaiacli tx sign unsignedTx.json --from <delegatorKeyName> --offline --chain-id cosmoshub-2 --sequence <sequence> --account-number <account-number> > signedTx.json
```
Copy `signedTx.json` and transfer it back to the online computer. Finally, use the following command to broadcast the transaction:
```bash
gaiacli tx broadcast signedTx.json
```

261
docs/cosmos-hub/deploy-testnet.md
View File

@ -1,261 +0,0 @@
# Deploy Your Own Gaia Testnet
This document describes 3 ways to setup a network of `gaiad` nodes, each serving a different usecase:
1. Single-node, local, manual testnet
2. Multi-node, local, automated testnet
3. Multi-node, remote, automated testnet
Supporting code can be found in the [networks directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks) and additionally the `local` or `remote` sub-directories.
> NOTE: The `remote` network bootstrapping may be out of sync with the latest releases and is not to be relied upon.
## Available Docker images
In case you need to use or deploy gaia as a container you could skip the `build` steps and use the official images, $TAG stands for the version you are interested in:
- `docker run -it -v ~/.gaiad:/root/.gaiad -v ~/.gaiacli:/root/.gaiacli tendermint:$TAG gaiad init`
- `docker run -it -p 26657:26657 -p 26656:26656 -v ~/.gaiad:/root/.gaiad -v ~/.gaiacli:/root/.gaiacli tendermint:$TAG gaiad start`
- ...
- `docker run -it -v ~/.gaiad:/root/.gaiad -v ~/.gaiacli:/root/.gaiacli tendermint:$TAG gaiacli version`
The same images can be used to build your own docker-compose stack.
## Single-node, Local, Manual Testnet
This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
### Requirements
- [Install gaia](./installation.md)
- [Install `jq`](https://stedolan.github.io/jq/download/) (optional)
### Create Genesis File and Start the Network
```bash
# You can run all of these commands from your home directory
cd $HOME
# Initialize the genesis.json file that will help you to bootstrap the network
gaiad init --chain-id=testing testing
# Create a key to hold your validator account
gaiacli keys add validator
# 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
gaiad add-genesis-account $(gaiacli keys show validator -a) 1000000000stake,1000000000validatortoken
# Generate the transaction that creates your validator
gaiad gentx --name validator
# Add the generated bonding transaction to the genesis file
gaiad collect-gentxs
# Now its safe to start `gaiad`
gaiad start
```
This setup puts all the data for `gaiad` in `~/.gaiad`. You can examine the genesis file you created at `~/.gaiad/config/genesis.json`. With this configuration `gaiacli` is also ready to use and has an account with tokens (both staking and custom).
## Multi-node, Local, Automated Testnet
From the [networks/local directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks/local):
### Requirements
- [Install gaia](./installation.md)
- [Install docker](https://docs.docker.com/engine/installation/)
- [Install docker-compose](https://docs.docker.com/compose/install/)
### Build
Build the `gaiad` binary (linux) and the `tendermint/gaiadnode` docker image required for running the `localnet` commands. This binary will be mounted into the container and can be updated rebuilding the image, so you only need to build the image once.
```bash
# Work from the SDK repo
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
# Build the linux binary in ./build
make build-linux
# Build tendermint/gaiadnode image
make build-docker-gaiadnode
```
### Run Your Testnet
To start a 4 node testnet run:
```
make localnet-start
```
This command creates a 4-node network using the gaiadnode image.
The ports for each node are found in this table:
| Node ID | P2P Port | RPC Port |
| --------|-------|------|
| `gaianode0` | `26656` | `26657` |
| `gaianode1` | `26659` | `26660` |
| `gaianode2` | `26661` | `26662` |
| `gaianode3` | `26663` | `26664` |
To update the binary, just rebuild it and restart the nodes:
```
make build-linux localnet-start
```
### Configuration
The `make localnet-start` creates files for a 4-node testnet in `./build` by
calling the `gaiad testnet` command. This outputs a handful of files in the
`./build` directory:
```bash
$ tree -L 2 build/
build/
├── gaiacli
├── gaiad
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   ├── gaiacli
│   │   ├── key_seed.json
│   │   └── keys
│   └── gaiad
│   ├── ${LOG:-gaiad.log}
│   ├── config
│   └── data
├── node1
│   ├── gaiacli
│   │   └── key_seed.json
│   └── gaiad
│   ├── ${LOG:-gaiad.log}
│   ├── config
│   └── data
├── node2
│   ├── gaiacli
│   │   └── key_seed.json
│   └── gaiad
│   ├── ${LOG:-gaiad.log}
│   ├── config
│   └── data
└── node3
├── gaiacli
│   └── key_seed.json
└── gaiad
├── ${LOG:-gaiad.log}
├── config
└── data
```
Each `./build/nodeN` directory is mounted to the `/gaiad` directory in each container.
### Logging
Logs are saved under each `./build/nodeN/gaiad/gaia.log`. You can also watch logs
directly via Docker, for example:
```
docker logs -f gaiadnode0
```
### Keys & Accounts
To interact with `gaiacli` and start querying state or creating txs, you use the
`gaiacli` directory of any given node as your `home`, for example:
```shell
gaiacli keys list --home ./build/node0/gaiacli
```
Now that accounts exists, you may create new accounts and send those accounts
funds!
::: tip
**Note**: Each node's seed is located at `./build/nodeN/gaiacli/key_seed.json` and can be restored to the CLI using the `gaiacli keys add --restore` command
:::
### Special Binaries
If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:
```
# Run with custom binary
BINARY=gaiafoo make localnet-start
```
## Multi-Node, Remote, Automated Testnet
The following should be run from the [networks directory](https://github.com/cosmos/cosmos-sdk/tree/develop/networks).
### Terraform & Ansible
Automated deployments are done using [Terraform](https://www.terraform.io/) to create servers on AWS then
[Ansible](http://www.ansible.com/) to create and manage testnets on those servers.
### Prerequisites
- Install [Terraform](https://www.terraform.io/downloads.html) and [Ansible](http://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) on a Linux machine.
- Create an [AWS API token](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) with EC2 create capability.
- Create SSH keys
```
export AWS_ACCESS_KEY_ID="2345234jk2lh4234"
export AWS_SECRET_ACCESS_KEY="234jhkg234h52kh4g5khg34"
export TESTNET_NAME="remotenet"
export CLUSTER_NAME= "remotenetvalidators"
export SSH_PRIVATE_FILE="$HOME/.ssh/id_rsa"
export SSH_PUBLIC_FILE="$HOME/.ssh/id_rsa.pub"
```
These will be used by both `terraform` and `ansible`.
### Create a Remote Network
```
SERVERS=1 REGION_LIMIT=1 make validators-start
```
The testnet name is what's going to be used in --chain-id, while the cluster name is the administrative tag in AWS for the servers. The code will create SERVERS amount of servers in each availability zone up to the number of REGION_LIMITs, starting at us-east-2. (us-east-1 is excluded.) The below BaSH script does the same, but sometimes it's more comfortable for input.
```
./new-testnet.sh "$TESTNET_NAME" "$CLUSTER_NAME" 1 1
```
### Quickly see the /status Endpoint
```
make validators-status
```
### Delete Servers
```
make validators-stop
```
### Logging
You can ship logs to Logz.io, an Elastic stack (Elastic search, Logstash and Kibana) service provider. You can set up your nodes to log there automatically. Create an account and get your API key from the notes on [this page](https://app.logz.io/#/dashboard/data-sources/Filebeat), then:
```
yum install systemd-devel || echo "This will only work on RHEL-based systems."
apt-get install libsystemd-dev || echo "This will only work on Debian-based systems."
go get github.com/mheese/journalbeat
ansible-playbook -i inventory/digital_ocean.py -l remotenet logzio.yml -e LOGZIO_TOKEN=ABCDEFGHIJKLMNOPQRSTUVWXYZ012345
```
### Monitoring
You can install the DataDog agent with:
```
make datadog-install
```

910
docs/cosmos-hub/gaiacli.md
View File

@ -1,910 +0,0 @@
# Gaia Client
## Gaia CLI
`gaiacli` is the tool that enables you to interact with the node that runs on the Cosmos Hub network, whether you run it yourself or not. Let us set it up properly. In order to install it, follow the [installation procedure](./installation.md).
### Setting up gaiacli
The main command used to set up `gaiacli` is the following:
```bash
gaiacli config <flag> <value>
```
It allows you to set a default value for each given flag.
First, set up the address of the full-node you want to connect to:
```bash
gaiacli config node <host>:<port
# example: gaiacli config node https://77.87.106.33:26657
```
If you run your own full-node, just use `tcp://localhost:26657` as the address.
Then, let us set the default value of the `--trust-node` flag:
```bash
gaiacli config trust-node true
# Set to true if you trust the full-node you are connecting to, false otherwise
```
Finally, let us set the `chain-id` of the blockchain we want to interact with:
```bash
gaiacli config chain-id cosmoshub-2
```
### Keys
#### Key Types
There are three types of key representations that are used:
- `cosmos`
- Derived from account keys generated by `gaiacli keys add`
- Used to receive funds
- e.g. `cosmos15h6vd5f0wqps26zjlwrc6chah08ryu4hzzdwhc`
* `cosmosvaloper`
- Used to associate a validator to it's operator
- Used to invoke staking commands
- e.g. `cosmosvaloper1carzvgq3e6y3z5kz5y6gxp3wpy3qdrv928vyah`
- `cosmospub`
- Derived from account keys generated by `gaiacli keys add`
- e.g. `cosmospub1zcjduc3q7fu03jnlu2xpl75s2nkt7krm6grh4cc5aqth73v0zwmea25wj2hsqhlqzm`
- `cosmosvalconspub`
- Generated when the node is created with `gaiad init`.
- Get this value with `gaiad tendermint show-validator`
- e.g. `cosmosvalconspub1zcjduepq0ms2738680y72v44tfyqm3c9ppduku8fs6sr73fx7m666sjztznqzp2emf`
#### Generate Keys
You'll need an account private and public key pair \(a.k.a. `sk, pk` respectively\) to be able to receive funds, send txs, bond tx, etc.
To generate a new _secp256k1_ key:
```bash
gaiacli keys add <account_name>
```
Next, you will have to create a passphrase to protect the key on disk. The output of the above
command will contain a _seed phrase_. It is recommended to save the _seed phrase_ in a safe
place so that in case you forget the password, you could eventually regenerate the key from
the seed phrase with the following command:
```bash
gaiacli keys add --recover
```
If you check your private keys, you'll now see `<account_name>`:
```bash
gaiacli keys show <account_name>
```
View the validator operator's address via:
```shell
gaiacli keys show <account_name> --bech=val
```
You can see all your available keys by typing:
```bash
gaiacli keys list
```
View the validator pubkey for your node by typing:
```bash
gaiad tendermint show-validator
```
Note that this is the Tendermint signing key, _not_ the operator key you will use in delegation transactions.
::: danger Warning
We strongly recommend _NOT_ using the same passphrase for multiple keys. The Tendermint team and the Interchain Foundation will not be responsible for the loss of funds.
:::
#### Generate Multisig Public Keys
You can generate and print a multisig public key by typing:
```bash
gaiacli keys add --multisig=name1,name2,name3[...] --multisig-threshold=K new_key_name
```
`K` is the minimum number of private keys that must have signed the
transactions that carry the public key's address as signer.
The `--multisig` flag must contain the name of public keys that will be combined into a
public key that will be generated and stored as `new_key_name` in the local database.
All names supplied through `--multisig` must already exist in the local database. Unless
the flag `--nosort` is set, the order in which the keys are supplied on the command line
does not matter, i.e. the following commands generate two identical keys:
```bash
gaiacli keys add --multisig=foo,bar,baz --multisig-threshold=2 multisig_address
gaiacli keys add --multisig=baz,foo,bar --multisig-threshold=2 multisig_address
```
Multisig addresses can also be generated on-the-fly and printed through the which command:
```bash
gaiacli keys show --multisig-threshold K name1 name2 name3 [...]
```
For more information regarding how to generate, sign and broadcast transactions with a
multi signature account see [Multisig Transactions](#multisig-transactions).
### Tx Broadcasting
When broadcasting transactions, `gaiacli` accepts a `--broadcast-mode` flag. This
flag can have a value of `sync` (default), `async`, or `block`, where `sync` makes
the client return a CheckTx response, `async` makes the client return immediately,
and `block` makes the client wait for the tx to be committed (or timing out).
It is important to note that the `block` mode should **not** be used in most
circumstances. This is because broadcasting can timeout but the tx may still be
included in a block. This can result in many undesirable situations. Therefor, it
is best to use `sync` or `async` and query by tx hash to determine when the tx
is included in a block.
### Fees & Gas
Each transaction may either supply fees or gas prices, but not both.
Validator's have a minimum gas price (multi-denom) configuration and they use
this value when when determining if they should include the transaction in a block during `CheckTx`, where `gasPrices >= minGasPrices`. Note, your transaction must supply fees that are greater than or equal to __any__ of the denominations the validator requires.
__Note__: With such a mechanism in place, validators may start to prioritize
txs by `gasPrice` in the mempool, so providing higher fees or gas prices may yield higher tx priority.
e.g.
```bash
gaiacli tx send ... --fees=50000uatom
```
or
```bash
gaiacli tx send ... --gas-prices=0.025uatom
```
### Account
#### Get Tokens
The best way to get tokens is from the [Cosmos Testnet Faucet](https://faucetcosmos.network). If the faucet is not working for you, try asking [#cosmos-validators](https://riot.im/app/#/room/#cosmos-validators:matrix.org). The faucet needs the `cosmos` from the account you wish to use for staking.
#### Query Account Balance
After receiving tokens to your address, you can view your account's balance by typing:
```bash
gaiacli query account <account_cosmos>
```
::: warning Note
When you query an account balance with zero tokens, you will get this error: `No account with address <account_cosmos> was found in the state.` This can also happen if you fund the account before your node has fully synced with the chain. These are both normal.
:::
### Send Tokens
The following command could be used to send coins from one account to another:
```bash
gaiacli tx send <sender_key_name_or_address> <recipient_address> 10faucetToken \
--chain-id=<chain_id>
```
::: warning Note
The `amount` argument accepts the format `<value|coin_name>`.
:::
::: tip Note
You may want to cap the maximum gas that can be consumed by the transaction via the `--gas` flag.
If you pass `--gas=auto`, the gas supply will be automatically estimated before executing the transaction.
Gas estimate might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction, thus an adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully. The adjustment can be controlled via the `--gas-adjustment` flag, whose default value is 1.0.
:::
Now, view the updated balances of the origin and destination accounts:
```bash
gaiacli query account <account_cosmos>
gaiacli query account <destination_cosmos>
```
You can also check your balance at a given block by using the `--block` flag:
```bash
gaiacli query account <account_cosmos> --block=<block_height>
```
You can simulate a transaction without actually broadcasting it by appending the
`--dry-run` flag to the command line:
```bash
gaiacli tx send <sender_key_name_or_address> <destination_cosmosaccaddr> 10faucetToken \
--chain-id=<chain_id> \
--dry-run
```
Furthermore, you can build a transaction and print its JSON format to STDOUT by
appending `--generate-only` to the list of the command line arguments:
```bash
gaiacli tx send <sender_address> <recipient_address> 10faucetToken \
--chain-id=<chain_id> \
--generate-only > unsignedSendTx.json
```
```bash
gaiacli tx sign \
--chain-id=<chain_id> \
--from=<key_name> \
unsignedSendTx.json > signedSendTx.json
```
::: tip Note
The `--generate-only` flag prevents `gaiacli` from accessing the local keybase.
Thus when such flag is supplied `<sender_key_name_or_address>` must be an address.
:::
You can validate the transaction's signatures by typing the following:
```bash
gaiacli tx sign --validate-signatures signedSendTx.json
```
You can broadcast the signed transaction to a node by providing the JSON file to the following command:
```bash
gaiacli tx broadcast --node=<node> signedSendTx.json
```
### Query Transactions
#### Matching a Set of Tags
You can use the transaction search command to query for transactions that match a specific set of `tags`, which are added on every transaction.
Each tag is conformed by a key-value pair in the form of `<tag>:<value>`. Tags can also be combined to query for a more specific result using the `&` symbol.
The command for querying transactions using a `tag` is the following:
```bash
gaiacli query txs --tags='<tag>:<value>'
```
And for using multiple `tags`:
```bash
gaiacli query txs --tags='<tag1>:<value1>&<tag2>:<value2>'
```
The pagination is supported as well via `page` and `limit`:
```bash
gaiacli query txs --tags='<tag>:<value>' --page=1 --limit=20
```
::: tip Note
The action tag always equals the message type returned by the `Type()` function of the relevant message.
You can find a list of available `tags` on each of the SDK modules:
- [Common tags](https://github.com/cosmos/cosmos-sdk/blob/d1e76221d8e28824bb4791cb4ad8662d2ae9051e/types/tags.go#L57-L63)
- [Staking tags](https://github.com/cosmos/cosmos-sdk/blob/d1e76221d8e28824bb4791cb4ad8662d2ae9051e/x/staking/tags/tags.go#L8-L24)
- [Governance tags](https://github.com/cosmos/cosmos-sdk/blob/d1e76221d8e28824bb4791cb4ad8662d2ae9051e/x/gov/tags/tags.go#L8-L22)
- [Slashing tags](https://github.com/cosmos/cosmos-sdk/blob/d1e76221d8e28824bb4791cb4ad8662d2ae9051e/x/slashing/handler.go#L52)
- [Distribution tags](https://github.com/cosmos/cosmos-sdk/blob/develop/x/distribution/tags/tags.go#L8-L17)
- [Bank tags](https://github.com/cosmos/cosmos-sdk/blob/d1e76221d8e28824bb4791cb4ad8662d2ae9051e/x/bank/keeper.go#L193-L206)
:::
#### Matching a Transaction's Hash
You can also query a single transaction by its hash using the following command:
```bash
gaiacli query tx [hash]
```
### Slashing
#### Unjailing
To unjail your jailed validator
```bash
gaiacli tx slashing unjail --from <validator-operator-addr>
```
#### Signing Info
To retrieve a validator's signing info:
```bash
gaiacli query slashing signing-info <validator-pubkey>
```
#### Query Parameters
You can get the current slashing parameters via:
```bash
gaiacli query slashing params
```
### Minting
You can query for the minting/inflation parameters via:
```bash
gaiacli query minting params
```
To query for the current inflation value:
```bash
gaiacli query minting inflation
```
To query for the current annual provisions value:
```bash
gaiacli query minting annual-provisions
```
### Staking
#### Set up a Validator
Please refer to the [Validator Setup](../validators/validator-setup.md) section for a more complete guide on how to set up a validator-candidate.
#### Delegate to a Validator
On the upcoming mainnet, you can delegate `atom` to a validator. These [delegators](/resources/delegators-faq) can receive part of the validator's fee revenue. Read more about the [Cosmos Token Model](https://github.com/cosmos/cosmos/raw/master/Cosmos_Token_Model.pdf).
##### Query Validators
You can query the list of all validators of a specific chain:
```bash
gaiacli query staking validators
```
If you want to get the information of a single validator you can check it with:
```bash
gaiacli query staking validator <account_cosmosval>
```
#### Bond Tokens
On the Cosmos Hub mainnet, we delegate `uatom`, where `1atom = 1000000uatom`. Here's how you can bond tokens to a testnet validator (_i.e._ delegate):
```bash
gaiacli tx staking delegate \
--amount=10000000uatom \
--validator=<validator> \
--from=<key_name> \
--chain-id=<chain_id>
```
`<validator>` is the operator address of the validator to which you intend to delegate. If you are running a local testnet, you can find this with:
```bash
gaiacli keys show [name] --bech val
```
where `[name]` is the name of the key you specified when you initialized `gaiad`.
While tokens are bonded, they are pooled with all the other bonded tokens in the network. Validators and delegators obtain a percentage of shares that equal their stake in this pool.
##### Query Delegations
Once submitted a delegation to a validator, you can see it's information by using the following command:
```bash
gaiacli query staking delegation <delegator_addr> <validator_addr>
```
Or if you want to check all your current delegations with disctinct validators:
```bash
gaiacli query staking delegations <delegator_addr>
```
#### Unbond Tokens
If for any reason the validator misbehaves, or you just want to unbond a certain
amount of tokens, use this following command.
```bash
gaiacli tx staking unbond \
<validator_addr> \
10atom \
--from=<key_name> \
--chain-id=<chain_id>
```
The unbonding will be automatically completed when the unbonding period has passed.
##### Query Unbonding-Delegations
Once you begin an unbonding-delegation, you can see it's information by using the following command:
```bash
gaiacli query staking unbonding-delegation <delegator_addr> <validator_addr>
```
Or if you want to check all your current unbonding-delegations with disctinct validators:
```bash
gaiacli query staking unbonding-delegations <account_cosmos>
```
Additionally, as you can get all the unbonding-delegations from a particular validator:
```bash
gaiacli query staking unbonding-delegations-from <account_cosmosval>
```
#### Redelegate Tokens
A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another:
```bash
gaiacli tx staking redelegate \
<src-validator-operator-addr> \
<dst-validator-operator-addr> \
10atom \
--from=<key_name> \
--chain-id=<chain_id>
```
Here you can also redelegate a specific `shares-amount` or a `shares-fraction` with the corresponding flags.
The redelegation will be automatically completed when the unbonding period has passed.
##### Query Redelegations
Once you begin an redelegation, you can see it's information by using the following command:
```bash
gaiacli query staking redelegation <delegator_addr> <src_val_addr> <dst_val_addr>
```
Or if you want to check all your current unbonding-delegations with distinct validators:
```bash
gaiacli query staking redelegations <account_cosmos>
```
Additionally, as you can get all the outgoing redelegations from a particular validator:
```bash
gaiacli query staking redelegations-from <account_cosmosval>
```
#### Query Parameters
Parameters define high level settings for staking. You can get the current values by using:
```bash
gaiacli query staking params
```
With the above command you will get the values for:
- Unbonding time
- Maximum numbers of validators
- Coin denomination for staking
All these values will be subject to updates though a `governance` process by `ParameterChange` proposals.
#### Query Pool
A staking `Pool` defines the dynamic parameters of the current state. You can query them with the following command:
```bash
gaiacli query staking pool
```
With the `pool` command you will get the values for:
- Not-bonded and bonded tokens
- Token supply
- Current annual inflation and the block in which the last inflation was processed
- Last recorded bonded shares
##### Query Delegations To Validator
You can also query all of the delegations to a particular validator:
```bash
gaiacli query delegations-to <account_cosmosval>
```
### Governance
Governance is the process from which users in the Cosmos Hub can come to consensus
on software upgrades, parameters of the mainnet or signaling mechanisms through
text proposals. This is done through voting on proposals, which will be submitted
by `ATOM` holders on the mainnet.
Some considerations about the voting process:
- Voting is done by bonded `ATOM` holders on a 1 bonded `ATOM` 1 vote basis
- Delegators inherit the vote of their validator if they don't vote
- Votes are tallied at the end of the voting period (2 weeks on mainnet) where
each address can vote multiple times to update its `Option` value (paying the transaction fee each time),
only the most recently cast vote will count as valid
- Voters can choose between options `Yes`, `No`, `NoWithVeto` and `Abstain`
- At the end of the voting period, a proposal is accepted iff:
- `(YesVotes / (YesVotes+NoVotes+NoWithVetoVotes)) > 1/2`
- `(NoWithVetoVotes / (YesVotes+NoVotes+NoWithVetoVotes)) < 1/3`
- `((YesVotes+NoVotes+NoWithVetoVotes) / totalBondedStake) >= quorum`
For more information about the governance process and how it works, please check
out the Governance module [specification](./../spec/governance).
#### Create a Governance Proposal
In order to create a governance proposal, you must submit an initial deposit
along with a title and description. Various modules outside of governance may
implement their own proposal types and handlers (eg. parameter changes), where
the governance module itself supports `Text` proposals. Any module
outside of governance has it's command mounted on top of `submit-proposal`.
To submit a `Text` proposal:
```bash
gaiacli tx gov submit-proposal \
--title=<title> \
--description=<description> \
--type="Text" \
--deposit="1000000uatom" \
--from=<name> \
--chain-id=<chain_id>
```
You may also provide the proposal directly through the `--proposal` flag which
points to a JSON file containing the proposal.
To submit a parameter change proposal, you must provide a proposal file as its
contents are less friendly to CLI input:
```bash
gaiacli tx gov submit-proposal param-change <path/to/proposal.json> \
--from=<name> \
--chain-id=<chain_id>
```
Where `proposal.json` contains the following:
```json
{
"title": "Param Change",
"description": "Update max validators",
"changes": [
{
"subspace": "staking",
"key": "MaxValidators",
"value": 105
}
],
"deposit": [
{
"denom": "stake",
"amount": "10000000"
}
]
}
```
::: danger Warning
Currently parameter changes are _evaluated_ but not _validated_, so it is very important
that any `value` change is valid (ie. correct type and within bounds) for its
respective parameter, eg. `MaxValidators` should be an integer and not a decimal.
Proper vetting of a parameter change proposal should prevent this from happening
(no deposits should occur during the governance process), but it should be noted
regardless.
:::
::: tip Note
The `SoftwareUpgrade` is currently not supported as it's not implemented and
currently does not differ from the semantics of a `Text` proposal.
:::
##### Query Proposals
Once created, you can now query information of the proposal:
```bash
gaiacli query gov proposal <proposal_id>
```
Or query all available proposals:
```bash
gaiacli query gov proposals
```
You can also query proposals filtered by `voter` or `depositor` by using the corresponding flags.
To query for the proposer of a given governance proposal:
```bash
gaiacli query gov proposer <proposal_id>
```
#### Increase Deposit
In order for a proposal to be broadcasted to the network, the amount deposited must be above a `minDeposit` value (initial value: `512000000uatom`). If the proposal you previously created didn't meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period:
```bash
gaiacli tx gov deposit <proposal_id> "10000000uatom" \
--from=<name> \
--chain-id=<chain_id>
```
> _NOTE_: Proposals that don't meet this requirement will be deleted after `MaxDepositPeriod` is reached.
##### Query Deposits
Once a new proposal is created, you can query all the deposits submitted to it:
```bash
gaiacli query gov deposits <proposal_id>
```
You can also query a deposit submitted by a specific address:
```bash
gaiacli query gov deposit <proposal_id> <depositor_address>
```
#### Vote on a Proposal
After a proposal's deposit reaches the `MinDeposit` value, the voting period opens. Bonded `Atom` holders can then cast vote on it:
```bash
gaiacli tx gov vote <proposal_id> <Yes/No/NoWithVeto/Abstain> \
--from=<name> \
--chain-id=<chain_id>
```
##### Query Votes
Check the vote with the option you just submitted:
```bash
gaiacli query gov vote <proposal_id> <voter_address>
```
You can also get all the previous votes submitted to the proposal with:
```bash
gaiacli query gov votes <proposal_id>
```
#### Query proposal tally results
To check the current tally of a given proposal you can use the `tally` command:
```bash
gaiacli query gov tally <proposal_id>
```
#### Query Governance Parameters
To check the current governance parameters run:
```bash
gaiacli query gov params
```
To query subsets of the governance parameters run:
```bash
gaiacli query gov param voting
gaiacli query gov param tallying
gaiacli query gov param deposit
```
### Fee Distribution
#### Query Distribution Parameters
To check the current distribution parameters, run:
```bash
gaiacli query distr params
```
#### Query distribution Community Pool
To query all coins in the community pool which is under Governance control:
```bash
gaiacli query distr community-pool
```
#### Query outstanding rewards
To check the current outstanding (un-withdrawn) rewards, run:
```bash
gaiacli query distr outstanding-rewards
```
#### Query Validator Commission
To check the current outstanding commission for a validator, run:
```bash
gaiacli query distr commission <validator_address>
```
#### Query Validator Slashes
To check historical slashes for a validator, run:
```bash
gaiacli query distr slashes <validator_address> <start_height> <end_height>
```
#### Query Delegator Rewards
To check current rewards for a delegation (were they to be withdrawn), run:
```bash
gaiacli query distr rewards <delegator_address> <validator_address>
```
#### Query All Delegator Rewards
To check all current rewards for a delegation (were they to be withdrawn), run:
```bash
gaiacli query distr rewards <delegator_address>
```
### Multisig Transactions
Multisig transactions require signatures of multiple private keys. Thus, generating and signing
a transaction from a multisig account involve cooperation among the parties involved. A multisig
transaction can be initiated by any of the key holders, and at least one of them would need to
import other parties' public keys into their Keybase and generate a multisig public key
in order to finalize and broadcast the transaction.
For example, given a multisig key comprising the keys `p1`, `p2`, and `p3`, each of which is held
by a distinct party, the user holding `p1` would require to import both `p2` and `p3` in order to
generate the multisig account public key:
```bash
gaiacli keys add \
p2 \
--pubkey=cosmospub1addwnpepqtd28uwa0yxtwal5223qqr5aqf5y57tc7kk7z8qd4zplrdlk5ez5kdnlrj4
gaiacli keys add \
p3 \
--pubkey=cosmospub1addwnpepqgj04jpm9wrdml5qnss9kjxkmxzywuklnkj0g3a3f8l5wx9z4ennz84ym5t
gaiacli keys add \
p1p2p3 \
--multisig-threshold=2 \
--multisig=p1,p2,p3
```
A new multisig public key `p1p2p3` has been stored, and its address will be
used as signer of multisig transactions:
```bash
gaiacli keys show --address p1p2p3
```
You may also view multisig threshold, pubkey constituents and respective weights
by viewing the JSON output of the key or passing the `--show-multisig` flag:
```bash
gaiacli keys show p1p2p3 -o json
gaiacli keys show p1p2p3 --show-multisig
```
The first step to create a multisig transaction is to initiate it on behalf
of the multisig address created above:
```bash
gaiacli tx send cosmos1570v2fq3twt0f0x02vhxpuzc9jc4yl30q2qned 1000000uatom \
--from=<multisig_address> \
--generate-only > unsignedTx.json
```
The file `unsignedTx.json` contains the unsigned transaction encoded in JSON.
`p1` can now sign the transaction with its own private key:
```bash
gaiacli tx sign \
unsignedTx.json \
--multisig=<multisig_address> \
--from=p1 \
--output-document=p1signature.json
```
Once the signature is generated, `p1` transmits both `unsignedTx.json` and
`p1signature.json` to `p2` or `p3`, which in turn will generate their
respective signature:
```bash
gaiacli tx sign \
unsignedTx.json \
--multisig=<multisig_address> \
--from=p2 \
--output-document=p2signature.json
```
`p1p2p3` is a 2-of-3 multisig key, therefore one additional signature
is sufficient. Any the key holders can now generate the multisig
transaction by combining the required signature files:
```bash
gaiacli tx multisign \
unsignedTx.json \
p1p2p3 \
p1signature.json p2signature.json > signedTx.json
```
The transaction can now be sent to the node:
```bash
gaiacli tx broadcast signedTx.json
```
## Shells Completion Scripts
Completion scripts for popular UNIX shell interpreters such as `Bash` and `Zsh`
can be generated through the `completion` command, which is available for both
`gaiad` and `gaiacli`.
If you want to generate `Bash` completion scripts run the following command:
```bash
gaiad completion > gaiad_completion
gaiacli completion > gaiacli_completion
```
If you want to generate `Zsh` completion scripts run the following command:
```bash
gaiad completion --zsh > gaiad_completion
gaiacli completion --zsh > gaiacli_completion
```
::: tip Note
On most UNIX systems, such scripts may be loaded in `.bashrc` or
`.bash_profile` to enable Bash autocompletion:
```bash
echo '. gaiad_completion' >> ~/.bashrc
echo '. gaiacli_completion' >> ~/.bashrc
```
Refer to the user's manual of your interpreter provided by your
operating system for information on how to enable shell autocompletion.
:::

60
docs/cosmos-hub/genesis-state.md
View File

@ -1,60 +0,0 @@
# Gaia Genesis State
Gaia genesis state, `GenesisState`, is composed of accounts, various module
states and metadata such as genesis transactions. Each module may specify its
own `GenesisState`. In addition, each module may specify its own genesis state
validation, import and export functionality.
The Gaia genesis state is defined as follows:
```go
type GenesisState struct {
Accounts []GenesisAccount `json:"accounts"`
AuthData auth.GenesisState `json:"auth"`
BankData bank.GenesisState `json:"bank"`
StakingData staking.GenesisState `json:"staking"`
MintData mint.GenesisState `json:"mint"`
DistrData distr.GenesisState `json:"distr"`
GovData gov.GenesisState `json:"gov"`
SlashingData slashing.GenesisState `json:"slashing"`
GenTxs []json.RawMessage `json:"gentxs"`
}
```
In the ABCI `initChainer` definition of Gaia the `initFromGenesisState` is called
which internally calls each module's `InitGenesis` providing its own respective
`GenesisState` as a parameter.
## Accounts
Genesis accounts defined in the `GenesisState` are defined as follows:
```go
type GenesisAccount struct {
Address sdk.AccAddress `json:"address"`
Coins sdk.Coins `json:"coins"`
Sequence uint64 `json:"sequence_number"`
AccountNumber uint64 `json:"account_number"`
// vesting account fields
OriginalVesting sdk.Coins `json:"original_vesting"` // total vesting coins upon initialization
DelegatedFree sdk.Coins `json:"delegated_free"` // delegated vested coins at time of delegation
DelegatedVesting sdk.Coins `json:"delegated_vesting"` // delegated vesting coins at time of delegation
StartTime int64 `json:"start_time"` // vesting start time (UNIX Epoch time)
EndTime int64 `json:"end_time"` // vesting end time (UNIX Epoch time)
}
```
Each account must have a valid and unique account number in addition to a
sequence number (nonce) and address.
Accounts may also be vesting, in which case they must provide the necessary vesting
information. Vesting accounts must provide at a minimum `OriginalVesting` and
`EndTime`. If `StartTime` is also provided, the account will be treated as a
"continuous" vesting account in which it vests coins at a predefined schedule.
Providing a `StartTime` must be less than `EndTime` but may be in the future.
In other words, it does not have to be equal to the genesis time. In a new chain
starting from a fresh state (not exported), `OriginalVesting` must be less than
or equal to `Coins.`
<!-- TODO: Remaining modules and components in GenesisState -->

332
docs/cosmos-hub/genesis.md
View File

@ -1,332 +0,0 @@
# Genesis File
This document explains how the genesis file of the Cosmos Hub mainnet is structured. It also explains how you can build a genesis file for your own `gaia` testnet.
Note that you can generate a default genesis file for your own testnet by running the following command:
```bash
gaiad init <moniker> --chain-id <chain-id>
```
The genesis file is stored in `~/.gaiad/config/genesis.toml`.
## What is a Genesis File
A genesis file is a JSON file which defines the initial state of your blockchain. It can be seen as height `0` of your blockchain. The first block, at height `1`, will reference the genesis file as its parent.
The state defined in the genesis file contains all the necessary information, like initial token allocation, genesis time, default parameters, and more. Let us break down these information.
## Genesis Time and Chain_id
The `genesis_time` is defined at the top of the genesis file. It is a `UTC` timestamps which specifies when the blockchain is due to start. At this time, genesis validators are supposed to come online and start participating in the consensus process. The blockchain starts when more than 2/3rd of the genesis validators (weighted by voting power) are online.
```json
"genesis_time": "2019-03-13T17:00:00.000000000Z",
```
The `chain_id` is a unique identifier for your chain. It helps differentiate between different chains using the same version of the software.
```json
"chain_id": "cosmoshub-1",
```
## Consensus Parameters
Next, the genesis file defines consensus parameters. Consensus parameters regroup all the parameters that are related to the consensus layer, which is `Tendermint` in the case of `gaia`. Let us look at these parameters:
- `block`
+ `max_bytes`: Maximum number of bytes per block.
+ `max_gas`: Gas limit per block. Each transaction included in the block will consume some gas. The total gas used by transactions included in a block cannot exceed this limit.
- `evidence`
+ `max_age`: An evidence is a proof that a validator signed two different blocks at the same height (and round). This is an explicitely malicious behaviour that is punished at the state-machine level. The `max_age` defines the maximum number of **blocks** after which an evidence is not valid anymore.
- `validator`
+ `pub_key_types`: The types of pubkey (`ed25519`, `secp256k1`, ...) that are accepted for validators. Currently only `ed25519` is accepted.
```json
"consensus_params": {
"block_size": {
"max_bytes": "150000",
"max_gas": "1500000"
},
"evidence": {
"max_age": "1000000"
},
"validator": {
"pub_key_types": [
"ed25519"
]
}
},
```
## Application State
The application state defines the initial state of the state-machine.
### Genesis Accounts
In this section, initial allocation of tokens is defined. It is possible to add accounts manually by directly editing the genesis file, but it is also possible to use the following command:
```bash
// Example: gaiad add-genesis-account cosmos1qs8tnw2t8l6amtzvdemnnsq9dzk0ag0z37gh3h 10000000uatom
gaiad add-genesis-account <account-address> <amount><denom>
```
This command creates an item in the `accounts` list, under the `app_state` section.
```json
"accounts": [
{
"address": "cosmos1qs8tnw2t8l6amtzvdemnnsq9dzk0ag0z37gh3h",
"coins": [
{
"denom": "uatom",
"amount": "10000000"
}
],
"sequence_number": "0",
"account_number": "0",
"original_vesting": [
{
"denom": "uatom",
"amount": "26306000000"
}
],
"delegated_free": null,
"delegated_vesting": null,
"start_time": "0",
"end_time": "10000"
}
]
```
Let us break down the parameters:
- `sequence_number`: This number is used to count the number of transactions sent by this account. It is incremented each time a transaction is included in a block, and used to prevent replay attacks. Initial value is `0`.
- `account_number`: Unique identifier for the account. It is generated the first time a transaction including this account is included in a block.
- `original_vesting`: Vesting is natively supported by `gaia`. You can define an amount of token owned by the account that needs to be vested for a period of time before they can be transferred. Vested tokens can be delegated. Default value is `null`.
- `delegated_free`: Amount of delegated tokens that can be transferred after they've been vested. Most of the time, will be `null` in genesis.
- `delegated_vesting`: Amount of delegated tokens that are still vesting. Most of the time, will be `null` in genesis.
- `start_time`: Block at which the vesting period starts. `0` most of the time in genesis.
- `end_time`: Block at which the vesting period ends. `0` if no vesting for this account.
### Bank
The `bank` module handles tokens. The only parameter that needs to be defined in this section is wether `transfers` are enabled at genesis or not.
```json
"bank": {
"send_enabled": false
}
```
### Staking
The `staking` module handles the bulk of the Proof-of-Stake logic of the state-machine. This section should look like the following:
```json
"staking": {
"pool": {
"not_bonded_tokens": "10000000",
"bonded_tokens": "0"
},
"params": {
"unbonding_time": "1814400000000000",
"max_validators": 100,
"max_entries": 7,
"bond_denom": "uatom"
},
"last_total_power": "0",
"last_validator_powers": null,
"validators": null,
"bonds": null,
"unbonding_delegations": null,
"redelegations": null,
"exported": false
}
```
Let us break down the parameters:
- `pool`
+ `not_bonded_tokens`: Defines the amount of tokens not bonded (i.e. delegated) in genesis. Generally, it equals the total supply of the staking token (`uatom` in this example).
+ `bonded_tokens`: Amount of bonded tokens in genesis. Generally `0`.
- `params`
+ `unbonding_time`: Time in **nanosecond** it takes for tokens to complete unbonding.
+ `max_validators`: Maximum number of active validators.
+ `max_entries`: Maximum unbonding delegations and redelegations between a particular pair of delegator / validator.
+ `bond_denom`: Denomination of the staking token.
- `last_total_power`: Total amount of voting power. Generally `0` in genesis (except if genesis was generated using a previous state).
- `last_validator_powers`: Power of each validator in last known state. Generally `null` in genesis (except if genesis was generated using a previous state).
- `validators`: List of last knoww validators. Generally `null` in genesis (except if genesis was generated using a previous state).
- `bonds`: List of last known delegation. Generally `null` in genesis (except if genesis was generated using a previous state).
- `unbonding_delegations`: List of last known unbonding delegations. Generally `null` in genesis (except if genesis was generated using a previous state).
- `redelegations`: List of last known redelegations. Generally `null` in genesis (except if genesis was generated using a previous state).
- `exported`: Wether this genesis was generated using the export of a previous state.
### Mint
The `mint` module governs the logic of inflating the supply of token. The `mint` section in the genesis file looks like the follwing:
```json
"mint": {
"minter": {
"inflation": "0.070000000000000000",
"annual_provisions": "0.000000000000000000"
},
"params": {
"mint_denom": "uatom",
"inflation_rate_change": "0.130000000000000000",
"inflation_max": "0.200000000000000000",
"inflation_min": "0.070000000000000000",
"goal_bonded": "0.670000000000000000",
"blocks_per_year": "6311520"
}
}
```
Let us break down the parameters:
- `minter`
+ `inflation`: Initial yearly percentage of increase in the total supply of staking token, compounded weekly. A `0.070000000000000000` value means the target is `7%` yearly inflation, compounded weekly.
+ `annual_provisions`: Calculated each block. Initialize at `0.000000000000000000`.
- `params`
+ `mint_denom`: Denom of the staking token that is inflated.
+ `inflation_rate_change`: Max yearly change in inflation.
+ `inflation_max`: Maximum level of inflation.
+ `inflation_min`: Minimum level of inflation.
+ `goal_bonded`: Percentage of the total supply that is targeted to be bonded. If the percentage of bonded staking tokens is below this target, the inflation increases (following `inflation_rate_change`) until it reaches `inflation_max`. If the percentage of bonded staking tokens is above this target, the inflation decreases (following `inflation_rate_change`) until it reaches `inflation_min`.
+ `blocks_per_year`: Estimation of the amount of blocks per year. Used to compute the block reward coming from inflated staking token (called block provisions).
### Distribution
The `distr` module handles the logic of distribution block provisions and fees to validators and delegators. The `distr` section in the genesis file looks like the follwing:
```json
"distr": {
"fee_pool": {
"community_pool": null
},
"community_tax": "0.020000000000000000",
"base_proposer_reward": "0.010000000000000000",
"bonus_proposer_reward": "0.040000000000000000",
"withdraw_addr_enabled": false,
"delegator_withdraw_infos": null,
"previous_proposer": "",
"outstanding_rewards": null,
"validator_accumulated_commissions": null,
"validator_historical_rewards": null,
"validator_current_rewards": null,
"delegator_starting_infos": null,
"validator_slash_events": null
}
```
Let us break down the parameters:
- `fee_pool`
+ `community_pool`: The community pool is a pool of tokens that can be used to pay for bounties. It is allocated via governance proposals. Generally `null` in genesis.
- `community_tax`: The tax percentage on fees and block rewards that goes to the community pool.
- `base_proposer_reward`: Base bonus on transaction fees collected in a valid block that goes to the proposer of block. If value is `0.010000000000000000`, 1% of the fees go to the proposer.
- `bonus_proposer_reward`: Max bonus on transaction fees collected in a valid block that goes to the proposer of block. The bonus depends on the number of `precommits` the proposer includes. If the proposer includes 2/3rd `precommits` weighted by voting power (minimum for the block to be valid), they get a bonus of `base_proposer_reward`. This bonus increases linearly up to `bonus_proposer_reward` if the proposer includes 100% of `precommits`.
- `withdraw_addr_enabled`: If `true`, delegators can set a different address to withdraw their rewards. Set to `false` if you want to disable transfers at genesis, as it can be used as a way to get around the restriction.
- `delegator_withdraw_infos`: List of delegators withdraw address. Generally `null` if genesis was not exported from previous state.
- `previous_proposer`: Proposer of the previous block. Set to `""` if genesis was not exported from previous state.
- `outstanding_rewards`: Outstanding (un-withdrawn) rewards. Set to `null` if genesis was not exported from previous state.
- `validator_accumulated_commission`: Outstanding (un-withdrawn) commission of validators. Set to `null` if genesis was not exported from previous state.
- `validator_historical_rewards`: Set of information related to the historical rewards of validators and used by the `distr` module for various computation. Set to `null` if genesis was not exported from previous state.
- `validators_current_rewards`: Set of information related to the current rewards of validators and used by the `distr` module for various computation. Set to `null` if genesis was not exported from previous state.
- `delegator_starting_infos`: Tracks the previous validator period, the delegation's amount of staking token, and the creation height (to check later on if any slashes have occurred). Set to `null` if genesis was not exported from previous state.
- `validator_slash_events`: Set of information related to the past slashing of validators. Set to `null` if genesis was not exported from previous state.
### Governance
The `gov` module handles all governance-related transactions. The initial state of the `gov` section looks like the following:
```json
"gov": {
"starting_proposal_id": "1",
"deposits": null,
"votes": null,
"proposals": null,
"deposit_params": {
"min_deposit": [
{
"denom": "uatom",
"amount": "512000000"
}
],
"max_deposit_period": "1209600000000000"
},
"voting_params": {
"voting_period": "1209600000000000"
},
"tally_params": {
"quorum": "0.4",
"threshold": "0.5",
"veto": "0.334",
"governance_penalty": "0.0"
}
}
```
Let us break down the parameters:
- `starting_proposal_id`: This parameter defines the ID of the first proposal. Each proposal is identified by a unique ID.
- `deposits`: List of deposits for each proposal ID. Set to `null` if genesis was not exported from previous state.
- `votes`: List of votes for each proposal ID. Set to `null` if genesis was not exported from previous state.
- `proposals`: List of proposals for each proposal ID: Set to `null` if genesis was not exported from previous state.
- `deposit_params`
+ `min_deposit`: The minimum deposit required for the proposal to enter `Voting Period`. If multiple denoms are provided, the `OR` operator applies.
+ `max_deposit_period`: The maximum period (in **nanoseconds**) after which it is not possible to deposit on the proposal anymore.
- `voting_params`
+ `voting_period`: Length of the voting period in **nanoseconds**.
- `tally_params`
+ `quorum`: Minimum percentage of bonded staking tokens that needs to vote for the result to be valid.
+ `threshold`: Minimum percentage of votes that need to be `YES` for the result to be valid.
+ `veto`: Maximum percentage `NO_WITH_VETO` votes for the result to be valid.
+ `governance_penalty`: Penalty for validators that do not vote on a given proposal.
### Slashing
The `slashing` module handles the logic to slash delegators if their validator misbehave. The `slashing` section in genesis looks as follows:
```json
"slashing": {
"params": {
"max_evidence_age": "1814400000000000",
"signed_blocks_window": "10000",
"min_signed_per_window": "0.050000000000000000",
"downtime_jail_duration": "600000000000",
"slash_fraction_double_sign": "0.050000000000000000",
"slash_fraction_downtime": "0.000100000000000000"
},
"signing_infos": {},
"missed_blocks": {}
}
```
Let us break down the parameters:
- `params`
+ `max_evidence_age`: Maximum age of the evidence in **nanoseconds**.
+ `signed_blocks_window`: Moving window of blocks to figure out offline validators.
+ `min_signed_per_window`: Minimum percentage of `precommits`that must be present in the `block window` for the validator to be considered online.
+ `downtime_jail_duration`: Duration in **nanoseconds** for which a validator is jailed after they get slashed for downtime.
+ `slash_fraction_double_sign`: Percentage of delegators bonded stake slashed when their validator double signs.
+ `slash_fraction_downtime`: Percentage of delegators bonded stake slashed when their validator is down.
- `signing_infos`: Various infos per validator needed by the `slashing` module. Set to `{}` if genesis was not exported from previous state.
- `missed_blocks`: Various infos related to missed blocks needed by the `slashing` module. Set to `{}` if genesis was not exported from previous state.
### Genesis Transactions
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
gaiad collect-gentxs
```
This command will add all the `gentxs` stored in `~/.gaiad/config/gentx` to the genesis file. In order to create a genesis transaction, click [here](./validators/validator-setup.md#participate-in-genesis-as-a-validator).

57
docs/cosmos-hub/hd-wallets.md
View File

@ -1,57 +0,0 @@
# HD Wallets
Accounts in Cosmos are Hierarichial Deterministic (HD) Wallets. Originally specified in Bitcoin's [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), HD wallets are a special kind of wallet that let users derive any number of accounts from a single seed. To understand what that means, let us first define some terminology:
- **Wallet**: Set of accounts obtained from a given seed.
- **Account**: A pair of public key/private key.
- **Private Key**: A private key is a secret piece of information used to sign messages. In the blockchain context, a private key identifies the owner of an account. The private key of a user should never be revealed to others.
- **Public Key**: A public key is a piece of information obtained by applying a one-way mathematical function on a private key. From it, an address can be derived. A private key cannot be found from a public key.
- **Address**: An address is a public string with a human-readable prefix that identifies an account. It is obtained by applying mathematical transformations to a public key.
- **Digital Signature**: A digital signature is a piece of cryptographic information that proves the owner of a given private key approved of a given message without revealing the private key.
- **Seed**: Same as Mnemonic.
- **Mnemonic**: A mnemonic is a sequence of words that is used as seed to derive private keys. The mnemonic is at the core of each wallet. NEVER LOSE YOUR MNEMONIC. WRITE IT DOWN ON A PIECE OF PAPER AND STORE IT SOMEWHERE SAFE. IF YOU LOSE IT, THERE IS NO WAY TO RETRIEVE IT. IF SOMEONE GAINS ACCESS TO IT, THEY GAIN ACCESS TO ALL THE ASSOCIATED ACCOUNTS.
At the core of a HD wallet, there is a seed. From this seed, users can deterministically generate accounts. To generate an account from a seed, one-way mathematical transformations are applied. To decide which account to generate, the user specifies a `path`, generally an `integer` (`0`, `1`, `2`, ...).
By specifying `path` to be `0` for example, the Wallet will generate `Private Key 0` from the seed. Then, `Public Key 0` can be generated from `Private Key 0`. Finally, `Address 0` can be generated from `Public Key 0`. All these steps are one way only, meaning the `Public Key` cannot be found from the `Address`, the `Private Key` cannot be found from the `Public Key`, ...
```
Account 0 Account 1 Account 2
+------------------+ +------------------+ +------------------+
| | | | | |
| Address 0 | | Address 1 | | Address 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Public key 0 | | Public key 1 | | Public key 2 |
| ^ | | ^ | | ^ |
| | | | | | | | |
| | | | | | | | |
| | | | | | | | |
| + | | + | | + |
| Private key 0 | | Private key 1 | | Private key 2 |
| ^ | | ^ | | ^ |
+------------------+ +------------------+ +------------------+
| | |
| | |
| | |
+--------------------------------------------------------------------+
|
|
+---------+---------+
| |
| Mnemonic (Seed) |
| |
+-------------------+
```
The process of derivating accounts from the seed is deterministic. This means that given the same path, the derived private key will always be the same.
The funds stored in an account are controlled by the private key. This private key is generated using a one-way function from the mnemonic. If you lose the private key, you can retrieve it using the mnemonic. However, if you lose the mnemonic, you will lose access to all the derived private keys. Likewise, if someone gains access to your mnemonic, they gain access to all the associated accounts.
::: danger
**Do not lose or share your 24 words with anyone. To prevent theft or loss of funds, it is best to keep multiple copies of your mnemonic stored in safe, secure places. If someone is able to gain access to your mnemonic, they will fully control the accounts associated with them.**
:::

71
docs/cosmos-hub/installation.md
View File

@ -1,71 +0,0 @@
## Install Gaia
This guide will explain how to install the `gaiad` and `gaiacli` entrypoints onto your system. With these installed on a server, you can participate in the mainnet as either a [Full Node](./join-mainnet.md) or a [Validator](./validators/validator-setup.md).
### Install Go
Install `go` by following the [official docs](https://golang.org/doc/install). Remember to set your `$GOPATH` and `$PATH` environment variables, for example:
```bash
mkdir -p $HOME/go/bin
echo "export GOPATH=$HOME/go" >> ~/.bash_profile
echo "export PATH=\$PATH:\$GOPATH/bin" >> ~/.bash_profile
source ~/.bash_profile
```
::: tip
**Go 1.12+** is required for the Cosmos SDK.
:::
### Install the binaries
Next, let's install the latest version of Gaia. Make sure you `git checkout` the correct [released version](https://github.com/cosmos/cosmos-sdk/releases).
::: warning
For the mainnet, make sure your version if greater than `v0.33.0`
:::
```bash
mkdir -p $GOPATH/src/github.com/cosmos
cd $GOPATH/src/github.com/cosmos
git clone https://github.com/cosmos/cosmos-sdk
cd cosmos-sdk && git checkout <latest-release-tag>
make tools install
```
> *NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
That will install the `gaiad` and `gaiacli` binaries. Verify that everything is OK:
```bash
$ gaiad version --long
$ gaiacli version --long
```
`gaiacli` for instance should output something similar to:
```
cosmos-sdk: 0.33.0
git commit: 7b4104aced52aa5b59a96c28b5ebeea7877fc4f0
vendor hash: 5db0df3e24cf10545c84f462a24ddc61882aa58f
build tags: netgo ledger
go version go1.12 linux/amd64
```
##### Build Tags
Build tags indicate special features that have been enabled in the binary.
| Build Tag | Description |
| --------- | ----------------------------------------------- |
| netgo | Name resolution will use pure Go code |
| ledger | Ledger devices are supported (hardware wallets) |
### Install binary distribution via snap (Linux only)
**Do not use snap at this time to install the binaries for production until we have a reproducible binary system.**
### Next
Now you can [join the mainnet](./join-mainnet.md), [the public testnet](./join-testnet.md) or [create you own testnet](./deploy-testnet.md)

182
docs/cosmos-hub/join-mainnet.md
View File

@ -1,182 +0,0 @@
# Join the mainnet
::: tip
See the [launch repo](https://github.com/cosmos/launch) for
information on the mainnet, including the correct version
of the Cosmos-SDK to use and details about the genesis file.
:::
::: warning
**You need to [install gaia](./installation.md) before you go further**
:::
## Setting Up a New Node
These instructions are for setting up a brand new full node from scratch.
First, initialize the node and create the necessary config files:
```bash
gaiad init <your_custom_moniker>
```
::: warning Note
Monikers can contain only ASCII characters. Using Unicode characters will render your node unreachable.
:::
You can edit this `moniker` later, in the `~/.gaiad/config/config.toml` file:
```toml
# A custom human readable name for this node
moniker = "<your_custom_moniker>"
```
You can edit the `~/.gaiad/config/gaiad.toml` file in order to enable the anti spam mechanism and reject incoming transactions with less than the minimum gas prices:
```
# 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. 10uatom).
minimum-gas-prices = ""
```
Your full node has been initialized!
## Genesis & Seeds
### Copy the Genesis File
Fetch the testnet's `genesis.json` file into `gaiad`'s config directory.
```bash
mkdir -p $HOME/.gaiad/config
curl https://raw.githubusercontent.com/cosmos/launch/master/genesis.json > $HOME/.gaiad/config/genesis.json
```
Note we use the `latest` directory in the [launch repo](https://github.com/cosmos/launch) which contains details for the mainnet like the latest version and the genesis file.
::: tip
If you want to connect to the public testnet instead, click [here](./join-testnet.md)
:::
To verify the correctness of the configuration run:
```bash
gaiad start
```
### Add Seed Nodes
Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.gaiad/config/config.toml`. The [`launch`](https://github.com/cosmos/launch) repo contains links to some seed nodes.
If those seeds aren't working, you can find more seeds and persistent peers on a Cosmos Hub explorer (a list can be found on the [launch page](https://cosmos.network/launch)).
You can also ask for peers on the [Validators Riot Room](https://riot.im/app/#/room/#cosmos-validators:matrix.org)
For more information on seeds and peers, you can [read this](https://github.com/tendermint/tendermint/blob/develop/docs/tendermint-core/using-tendermint.md#peers).
## A Note on Gas and Fees
::: warning
On Cosmos Hub mainnet, the accepted denom is `uatom`, where `1atom = 1.000.000uatom`
:::
Transactions on the Cosmos Hub network need to include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. The formula is the following:
```
fees = ceil(gas * gasPrices)
```
The `gas` is dependent on the transaction. Different transaction require different amount of `gas`. The `gas` amount for a transaction is calculated as it is being processed, but there is a way to estimate it beforehand by using the `auto` value for the `gas` flag. Of course, this only gives an estimate. You can adjust this estimate with the flag `--gas-adjustment` (default `1.0`) if you want to be sure you provide enough `gas` for the transaction.
The `gasPrice` is the price of each unit of `gas`. Each validator sets a `min-gas-price` value, and will only include transactions that have a `gasPrice` greater than their `min-gas-price`.
The transaction `fees` are the product of `gas` and `gasPrice`. As a user, you have to input 2 out of 3. The higher the `gasPrice`/`fees`, the higher the chance that your transaction will get included in a block.
::: tip
For mainnet, the recommended `gas-prices` is `0.025uatom`.
:::
## Set `minimum-gas-prices`
Your full-node keeps unconfirmed transactions in its mempool. In order to protect it from spam, it is better to set a `minimum-gas-prices` that the transaction must meet in order to be accepted in your node's mempool. This parameter can be set in the following file `~/.gaiad/config/gaiad.toml`.
The initial recommended `min-gas-prices` is `0.025uatom`, but you might want to change it later.
## Run a Full Node
Start the full node with this command:
```bash
gaiad start
```
Check that everything is running smoothly:
```bash
gaiacli status
```
View the status of the network with the [Cosmos Explorer](https://cosmos.network/launch).
## Export State
Gaia can dump the entire application state to a JSON file, which could be useful for manual analysis and can also be used as the genesis file of a new network.
Export state with:
```bash
gaiad export > [filename].json
```
You can also export state from a particular height (at the end of processing the block of that height):
```bash
gaiad export --height [height] > [filename].json
```
If you plan to start a new network from the exported state, export with the `--for-zero-height` flag:
```bash
gaiad export --height [height] --for-zero-height > [filename].json
```
## Verify Mainnet
Help to prevent a catastrophe by running invariants on each block on your full
node. In essence, by running invariants you ensure that the state of mainnet is
the correct expected state. One vital invariant check is that no atoms are
being created or destroyed outside of expected protocol, however there are many
other invariant checks each unique to their respective module. Because invariant checks
are computationally expensive, they are not enabled by default. To run a node with
these checks start your node with the assert-invariants-blockly flag:
```bash
gaiad start --assert-invariants-blockly
```
If an invariant is broken on your node, your node will panic and prompt you to send
a transaction which will halt mainnet. For example the provided message may look like:
```bash
invariant broken:
loose token invariance:
pool.NotBondedTokens: 100
sum of account tokens: 101
CRITICAL please submit the following transaction:
gaiacli tx crisis invariant-broken staking supply
```
When submitting a invariant-broken transaction, transaction fee tokens are not
deducted as the blockchain will halt (aka. this is a free transaction).
## Upgrade to Validator Node
You now have an active full node. What's the next step? You can upgrade your full node to become a Cosmos Validator. The top 100 validators have the ability to propose new blocks to the Cosmos Hub. Continue onto [the Validator Setup](./validators/validator-setup.md).

62
docs/cosmos-hub/join-testnet.md
View File

@ -1,62 +0,0 @@
# Join the Public Testnet
::: tip Current Testnet
See the [testnet repo](https://github.com/cosmos/testnets) for
information on the latest testnet, including the correct version
of the Cosmos-SDK to use and details about the genesis file.
:::
::: warning
**You need to [install gaia](./installation.md) before you go further**
:::
## Starting a New Node
> NOTE: If you ran a full node on a previous testnet, please skip to [Upgrading From Previous Testnet](#upgrading-from-previous-testnet).
To start a new node, the mainnet instructions apply:
- [Join the mainnet](./join-mainnet.md)
- [Deploy a validator](./validators/validator-setup.md)
The only difference is the SDK version and genesis file. See the [testnet repo](https://github.com/cosmos/testnets) for information on testnets, including the correct version of the Cosmos-SDK to use and details about the genesis file.
## Upgrading Your Node
These instructions are for full nodes that have ran on previous versions of and would like to upgrade to the latest testnet.
### Reset Data
First, remove the outdated files and reset the data.
```bash
rm $HOME/.gaiad/config/addrbook.json $HOME/.gaiad/config/genesis.json
gaiad unsafe-reset-all
```
Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before,
your node will still try to connect to them, but may fail if they haven't also
been upgraded.
::: danger Warning
Make sure that every node has a unique `priv_validator.json`. Do not copy the `priv_validator.json` from an old node to multiple new nodes. Running two nodes with the same `priv_validator.json` will cause you to double sign.
:::
### Software Upgrade
Now it is time to upgrade the software:
```bash
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
git fetch --all && git checkout master
make update_tools install
```
::: tip
*NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
:::
Note we use `master` here since it contains the latest stable release.
See the [testnet repo](https://github.com/cosmos/testnets) for details on which version is needed for which testnet, and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases) for details on each release.
Your full node has been cleanly upgraded!

10
docs/cosmos-hub/keys.md
View File

@ -1,10 +0,0 @@
# Keys
See the [Tendermint specification](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/encoding.md#public-key-cryptography) for how we work with keys.
See `gaiacli keys --help`.
Also see the [testnet
tutorial](https://github.com/cosmos/cosmos-sdk/tree/develop/cmd/gaia/testnets).
TODO: cleanup the UX and document this properly

71
docs/cosmos-hub/launch/blog-1-cn.md
View File

@ -1,71 +0,0 @@
# Cosmos Hub主网上线计划
* 2016年夏天，Cosmos首次发表了项目白皮书。
* 2017年春天，Cosmos完成了首次募资。
* 2019年一月，Cosmos Hub软件完成功能开发。
* 至此，Cosmos Hub主网即将启动。
* 那么，Cosmos 主网上线将为Cosmos通证（Atom）的持有者带来什么呢？
如果你是一个Atom通证的持有者，你可以将通证委托给主网的验证人并参加对链上治理提案的投票。 实际上，通证持有者的委托和参与治理对于未来网络的成功具有决定性的意义。 然而，通证持有者暂时还不能在网络上实现交易。 在下一个允许交易的硬分叉启动之前，交易协议是关闭的。
**Atom通证持有人务必仔细阅读以下内容，以保障您的通证能够安全委托给验证人。在您开始实际操作前，请先仔细阅读整个CLI指南并熟悉所有命令**
* [CLI指南](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/gaia/delegator-guide-cli.md)
CLI指南中所介绍的流程是至今为止唯一经过验证的在主网实现通证委托的安全途径。这是因为指南中用到的gaiacli工具是唯一正在进行第三方安全审计的数字钱包软件，目前尚没有其他数字钱包供应商通过类似的安全审计。
请记住，通证委托有一定风险。 一旦您将通证委托给了一个验证人，通证将在委托期内锁定，无法回收。 如果在这段时间内，被委托的验证人有任何违规行为，您的部分或者全部通证将被罚没焚毁。因此，在委托前，您有责任对验证人进行尽职调查。
**Cosmos Hub主网仍然是个实验型的网络。在主网的早期，估计仍会出现一些问题，比如软件升级，或发现新的漏洞。现有的工具要求使用者具有很高的专业技术能力，并且可能还会存在我们跨链基金会或者Tendermint团队无法控制的风险（请见跨链 Cosmos 贡献条款中的风险部分条款）。使用Cosmos Hub开源软件需要遵守Apache 2.0授权协议，使用者需要自己承担所有风险，而且软件将依照“现状”提供，不提供任何形式的保证或条件，并且跨链基金会和/或Tendermint团队不对因软件引起的损失承担任何责任。所以，务必请谨慎行事！**
* [跨链 Cosmos 贡献条款](https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf)
* [Apache 2.0授权协议](https://www.apache.org/licenses/LICENSE-2.0)
如果您希望获得更多关于通证委托的介绍并且愿意和Cosmos的开发者做直接的交流，您可以参加我们2月14日的线上直播，在直播中我们将介绍主网启动后通证委托的整个流程。
注册链接：[gotowebinar.com/register/](https://register.gotowebinar.com/register/5028753165739687691)
## 主网启动的里程碑
欢迎收藏[cosmos.network/launch](https://cosmos.network/launch)，跟踪主网启动全过程。
* Cosmos-SDK 安全审计✔: 在1月初，Cosmos-SDK启动了2019年一季度计划进行的一系列第三方安全评估的第一个评估项目。此次安全评估审计持续2周半的时间，2个不同的安全审计公司对Cosmos-SDK各部分做了安全评估，而第三家安全审计公司的评估工作也正在进行中。
* Cosmos-SDK正式发布版本: RC版本一旦完成，Cosmos-SDK的功能在主网上线前将不再变更，此后Cosmos-SDK团队将开始一轮内部漏洞检测，以便进一步确保在发布前完成最终的安全性检查。Cosmos-SDK v0.31.0 一发布，我们将启动一个新的Gaia测试网，以便在实际运行环境中找到那些在测试中难以被发现的漏洞。
* 权益争夺赛结束: 2018年12月启动的权益争夺赛（GoS）是同类区块链网络的第一个对抗性的测试网络。GoS旨在对纯PoS网络中的经济激励和社区协作进行压力测试。到目前为止，GoS区块链网络已经完成了3次硬分叉。GoS任务结束后，我们将通过记分准则来判断获胜者，并且在整个活动结束时宣布对获胜者的奖励。[GoS记分准则](https://github.com/cosmos/game-of-stakes/blob/master/README.md#scoring)
* 创世交易的收集: 跨链基金会将对创世时Atom通证的分配情况发布一个议案，提出了对Cosmos投资者，参与者，早期贡献者和权益争夺赛的获胜者的通证分配方案。任何被推荐获得通证分配的个人（或机构）都可以提交一个gentx文件，只有提交了该文件才有可能在主网启动创世时成为Cosmos验证人。推荐分配数量和gentx收集的最终结果将保存在创世genesis文件中
* Cosmos Hub 主网启动🔥 🚀 🌔🔥: 一旦社区接受了genesis文件， 并且占有2/3以上投票权的验证人们上线，Cosmos主网就可以启动了。
## Cosmos官方交流渠道
**以下是Cosmos有关主网启动的官方渠道**
* Cosmos Network (twitter.com/cosmos)
* Cosmos GitHub (github.com/cosmos)
* Cosmos Blog (blog.cosmos.network)
**请注意Cosmos forum，Riot群，和Telegram群将不被视为官方信息发布渠道。**
* [Cosmos forum](https://forum.cosmos.network)
* [Riot群](https://riot.im/app/#/group/+cosmos:matrix.org)
* [Telegram群](http://t.me/cosmosproject)
如果你对下一步应该做什么或者消息来源的可信度还有什么疑虑，那么在启动时请先不要有任何行动，您可以关注以上三个Cosmos官方渠道发布的最新情况，另外不要向任何管理员、网站或者非官方软件提供您的助记词。
切记，我们绝不会要求您提供您的私钥或者助记词。
## 在主网启动期间确保资产安全可靠
任何公链启动都会令人十分激动，但同时也会有一些唯利是图的人趁机作恶。自人类起源，社会工程学就已经存在了，在当今技术时代，网络钓鱼和鱼叉式网钓是利用社会工程学原理实行欺诈的主要形式。这两种攻击方式都非常有效，95%以上的账户安全漏洞都是由这两种攻击造成的，而且现在也不仅是通过电子邮件来发动攻击这么简单了。今天，网络钓鱼可能会随机或有针对性地发生在您所有的信息接收渠道，无论您是使用Signal，Telegram，SMS，Twitter或只是在论坛、社交媒体上接收信息，都有可能受到网络攻击，盗取您的重要信息和资产。
虽然作恶者的攻击听起来很可怕，但我们仍可以做很多事情来保护自己免受各种攻击。在准备主网启动期间，我们有必要为您提供一些培训来提高您发现和规避安全风险的能力，提供验证信息的可靠渠道，并通过一些技术手段来减少或避免关键风险和证件被窃风险。
## 安全规则
#### 参与Cosmos主网启动，您需要熟记以下规则:
* 直接从官方来源下载软件，并确保在您进行助记词相关的任何操作时始终使用最新、最安全的gaiacli版本。最新版的Tendermint，Cosmos-SDK和gaiacli只能从我们官方GitHub仓库中获取，从这些渠道下载可避免上当受骗，避免使用恶意修改的软件版本。
* 不要将助记词告诉给任何人，你是助记词的唯一保管人。如果有人试图为您的Atom提供托管服务，那么就要警惕了：为了避免对通证失去控制，您应该将其离线存储，最大限度降低被盗风险，并制定安全的备份策略，永远不要与任何人分享。
* 对于在区块链或加密货币环境中要求您访问来自可疑或不熟悉网站的附件或电子邮件要保持警惕。攻击者可能会试图引诱您访问虚假网站，以从您的计算机窃取敏感信息。如果您是Gmail用户，[请在此处对钓鱼邮件进行测试](https://phishingquiz.withgoogle.com)。
* 在购买Atoms之前，请做好充分的信息调研。通证在主网启动时是不允许交易的，所以它们不能进行买卖。只有到实现交易功能的硬叉发布后才能实现通证的在线交易。通证的在线交易功能实现后，请首先对卖方和交易所进行全面调研，确保Atom通证的来源可信。
* Tendermint团队和跨链基金会都不会出售Atom通证，所以，如果您在社交媒体或者电子邮件中看到我们发出的通证销售广告，请不要相信，一定是假的。
* 对于来自论坛或者技术交流群中的陌生人提供的技术建议必须保持警惕！您需要熟悉所有重要的指令，特别是那些可能存在高风险的操作指令。您可以查阅我们的官方文档，以避免上当受骗，损害自身及他人的利益。请牢记：Cosmos论坛，Riot群，和Telegram群都不是Cosmos官方信息或者新闻的发布渠道。
* 在发送交易前再次确认交易。链上地址的确很长，但请仔细检查，确保交易发送到正确的地址，防止错误发送。
如果突然出现的交易极具诱惑，或显示的消息要求您提供永远不应该与其他人分享的信息，您就应该立刻通过Cosmos网站或者其他官方渠道来验证这些信息。请再次牢记，来自Cosmos，Tendermint团队或跨链基金会的任何人都不会发送电子邮件要求您提供任何类型的帐户凭据或您的助记词，我们仅会通过我们的官方博客，Twitter和GitHub帐户与Cosmos社区沟通重要新闻和进展。

222
docs/cosmos-hub/launch/blog-1-en.md
View File

@ -1,222 +0,0 @@
# Cosmos Hub to Launch Mainnet
## Pre-launch Dependencies & How to Safely Claim Your Atoms
In the summer of 2016, the [Cosmos whitepaper][whitepaper] was released. In the
spring of 2017, the [Cosmos fundraiser][fundraiser] was completed. In the first
months of 2019, the software is [feature complete][releases]. The launch of the
Cosmos Hub draws near. What does this mean for Atom holders?
If you are an Atom holder, you will be able to delegate Atoms to validators on
the main network and vote on governance proposals. In fact, the future success
of the network depends on you responsibly doing so! However, you will not be
able to transfer Atoms yet. Transfers will be disabled at the protocol level
until a hard-fork is executed to enable them.
Atom holders should carefully follow the guidelines in order to safely delegate
Atoms. Please read through the entire guide first to familiarize yourself
before you actually do anything: [CLI guide][cli]
The process outlined in the guide is currently the only verified and secure way
to delegate Atoms at launch. This is because the gaiacli tool used in the guide
is the only wallet software undergoing third-party security audits right now.
No other wallet providers have begun security audits yet.
Remember that delegating Atoms involves significant risk. Once delegated to a
validator, Atoms are bonded for a period of time during which they cannot be
recovered. If the validator misbehaves during this time, some or all of the
delegated Atoms may be burned. It is your responsibility to perform due
diligence on validators before delegating!
The Cosmos Hub is highly experimental software. In these early days, we can
expect to have issues, updates, and bugs. The existing tools require advanced
technical skills and involve risks which are outside of the control of the
Interchain Foundation and/or the Tendermint team (see also the risk section in
the [Interchain Cosmos Contribution Terms][terms]). Any use of this open source
[Apache 2.0 licensed][apache] software is done at your own risk and on a “AS
IS” basis without warranties or conditions of any kind, and any and all
liability of the Interchain Foundation and/or the Tendermint team for damages
arising in connection to the software is excluded. Please exercise extreme
caution!
If you are looking for more information about delegation and want to talk to
the folks developing Cosmos, join the virtual meetup on February 14 where you
will be walked through the step-by-step instructions for delegating Atoms at
launch.
Register here: [gotowebinar.com/register/][webinar]
## Remaining Milestones for Launch
To follow mainnet launch progress, please bookmark:
[cosmos.network/launch][cosmos].
### 5 Cosmos-SDK Security Audits ✔
In early January, the Cosmos-SDK underwent the first in a series of third-party
security assessments scheduled for Q1 2019. This audit took place over a two
and a half week period. To date, two different security auditing firms have
assessed various parts of the Cosmos-SDK and a third audit is under way.
### 4 Cosmos SDK Feature Freeze
The final breaking changes to the Cosmos-SDK are included in the [v0.31.0
launch RC][rc]. Once this RC is completed, the Cosmos-SDK team will engage in a
round of internal bug hunting to further ensure sufficient pre-launch security
due diligence.
Right after Cosmos-SDK v0.31.0 is released, a Gaia testnet will be released in
an effort to flush out any hard to find bugs.
### 3 Game of Stakes Completed
Game of Stakes (GoS), [the first adversarial testnet competition of its
kind][gos], was launched in December 2018 to stress test the economic incentive
and social layers of a blockchain network secured purely by Proof-of-Stake. The
GoS blockchain was successfully hard-forked three times to date. As soon as the
GoS concludes, the [scoring criteria][scoring] will be used to determine
winners. Those will be announced following the completion of the game.
### 2 Genesis Transactions Collected
The Interchain Foundation will publish a recommendation for the allocation of
Atoms at genesis. This will include allocations for Cosmos fundraiser
participants, early contributors, and Game of Stakes winners. Any one with a
recommended allocation will have the opportunity to submit a gentx, which is
required to become a validator at genesis. The ultimate result of the
recommended allocation and the collection of gentxs is a final [genesis
file][file].
### 1 Cosmos Hub Mainnet Launch
Once a genesis file is adopted by the community, and +⅔ of the voting power
comes online, the Cosmos mainnet will be live.
## Official Cosmos Communication Channels
These are the official accounts that will communicate launch details:
- [Cosmos Network](https://twitter.com/cosmos)
- [Cosmos GitHub](https://github.com/cosmos)
- [Cosmos Blog](https://blog.cosmos.network)
Please be aware that the [Cosmos forum][forum], [Riot chat groups][riot], and
[Telegram group][telegram] should not be treated as official news from Cosmos.
If you have doubt or confusion about what next steps to take and are unsure
about trustworthy sources of information, do nothing for the initial period and
wait for an update via the three communication channels listed above. Do not
ever provide your 12 words to any admin, websites or unofficial software.
**We will never ask you for your private key or your seed phrase.**
## Staying Safe (and Secure!) for Mainnet Launch
The launch of any public blockchain is an incredibly exciting time, and it’s
definitely one that malicious actors may try to take advantage of for their own
personal gain. [Social engineering][social] has existed for about as long as
human beings have been on the planet, and in the technical era, it usually
takes in the form of [phishing] or [spearphishing]. Both of these attacks are
wildly successful forms of trickery that are responsible for over 95% of
account security breaches, and they don’t just happen via email: these days,
opportunistic and targeted phishing attempts take place [anywhere that you have
an inbox][inbox]. It doesn’t matter if you’re using Signal, Telegram, SMS,
Twitter, or just checking your DMs on forums or social networks, attackers have
a [plethora of opportunities][opportunities] to gain foothold in your digital
life in effort to separate you from valuable information and assets that you
most definitely don’t want to lose.
While the prospect of having to deal with a malicious actor plotting against
you may seem daunting, there are many things that you can do to protect
yourself from all kinds of social engineering schemes. In terms of preparing
for mainnet launch, this should require training your instincts to successfully
detect and avoid security risks, curating resources to serve as a source of
truth for verifying information, and going through a few technical steps to
reduce or eliminate the risk of key or credential theft.
**Here are few rules of engagement to keep in mind when you’re preparing for
Cosmos mainnet launch:**
- Download software directly from official sources, and make sure that you’re
always using the latest, most secure version of gaiacli when you’re doing
anything that involves your 12 words. The latest versions of Tendermint, the
Cosmos-SDK, and gaiacli will always be available from our official GitHub
repositories, and downloading them from there ensures that you will not be
tricked into using a maliciously modified version of software.
- Do not share your 12 words with anyone. The only person who should ever need
to know them is you. This is especially important if you’re ever approached
by someone attempting to offer custodial services for your Atom: to avoid
losing control of your tokens, you should store them offline to minimize the
risk of theft and have a strong backup strategy in place. And never, ever
share them with anyone else.
- Be skeptical of unexpected attachments or emails that ask you to visit a
suspicious or unfamiliar website in the context of blockchains or
cryptocurrency. An attacker may attempt to lure you to a [compromised site]
designed to steal sensitive information from your computer. If you’re a Gmail
user, test your resilience against the latest email-based phishing tactics
[here][quiz].
- Do your due diligence before purchasing Atoms. Atoms will not be transferable
at launch, so they *cannot* be bought or sold until a hard fork enables them
to be. If and when they become transferable, make sure that you’ve researched
the seller or exchange to confirm that the Atoms are coming from a
trustworthy source.
- Neither the Tendermint team nor the Interchain Foundation will be selling
Atoms, so if you see social media posts or emails advertising a token sale
from us, they’re not real and should be avoided. Enable 2-factor
authentication, and be mindful of recovery methods used to regain access to
your most important accounts. Unprotected accounts like email, social media,
your GitHub account, the Cosmos Forum and anything in between could give an
attacker opportunities to gain foothold in your online life. If you haven’t
done so yet, start using an authenticator app or a hardware key immediately
wherever you manage your tokens. This is a simple, effective, and proven way
to reduce the risk of account theft.
- Be skeptical of technical advice, especially advice that comes from people
you do not know in forums and on group chat channels. Familiarize yourself
with important commands, especially those that will help you carry out
high-risk actions, and consult our official documentation to make sure that
you’re not being tricked into doing something that will harm you or your
validator. And remember that the Cosmos forum, Riot channels, and Telegram
are not sources of official information or news about Cosmos.
- Verify transactions before hitting send. Yes, those address strings are long,
but visually comparing them in blocks of 4 characters at a time may be the
difference between sending them to the right place or sending them into
oblivion.
*If a deal pops up that [sounds too good to be true][good], or a message shows
up asking for information that should never, ever be shared with someone else,
you can always work to verify it before engaging with it by navigating to a
website or official Cosmos communication channel on your own. No one from
Cosmos, the Tendermint team or the Interchain Foundation will ever send an
email that asks for you to share any kind of account credentials or your 12
words with us, and we will always use our official blog, Twitter and GitHub
accounts to communicate important news directly to the Cosmos community.*
[whitepaper]: https://cosmos.network/resources/whitepaper
[fundraiser]: https://fundraiser.cosmos.network/
[releases]: https://github.com/cosmos/cosmos-sdk/releases
[cosmos]: https://cosmos.network/launch
[social]: https://en.wikipedia.org/wiki/Social_engineering_%28security%29
[phishing]: https://ssd.eff.org/en/module/how-avoid-phishing-attacks
[spearphishing]: https://en.wikipedia.org/wiki/Phishing#Spear_phishing
[inbox]: https://www.umass.edu/it/security/phishing-fraudulent-emails-text-messages-phone-calls
[opportunities]: https://jia.sipa.columbia.edu/weaponization-social-media-spear-phishing-and-cyberattacks-democracy
[cli]: https://github.com/cosmos/cosmos-sdk/blob/develop/docs/gaia/delegator-guide-cli.md
[webinar]: https://register.gotowebinar.com/register/5028753165739687691
[terms]: https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf
[apache]: https://www.apache.org/licenses/LICENSE-2.0
[gos]: https://blog.cosmos.network/announcing-incentivized-testnet-game-efe64e0956f6
[scoring]: https://github.com/cosmos/game-of-stakes/blob/master/README.md#scoring
[file]: https://forum.cosmos.network/t/genesis-files-network-starts-vs-upgrades/1464
[forum]: https://forum.cosmos.network/
[riot]: https://riot.im/app/#/group/+cosmos:matrix.org
[telegram]: http://t.me/cosmosproject
[good]: https://www.psychologytoday.com/us/blog/mind-in-the-machine/201712/how-fear-is-being-used-manipulate-cryptocurrency-markets
[rc]: https://github.com/cosmos/cosmos-sdk/projects/27
[compromised site]: https://blog.malwarebytes.com/cybercrime/2013/02/tools-of-the-trade-exploit-kits/
[quiz]: https://phishingquiz.withgoogle.com/

82
docs/cosmos-hub/launch/blog-1-kr.md
View File

@ -1,82 +0,0 @@
# 코스모스 허브 메인넷의 시작
#### 런칭 준비 체크리스트 & 안전하게 아톰 수령하기
2016년 여름, 코스모스 [백서가](https://cosmos.network/resources/whitepaper) 세상에 공개되었습니다. 이후 2017년 봄, 코스모스의 [펀드레이저가](펀드레이저가) 성공적으로 완료되었습니다. 그리고 2019년 2월, 코스모스의 소프트웨어[가 기능 완성](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.31.0)(feature complete)단계에 도달했습니다. 이제 코스모스 허브의 런칭을 앞두고 있는 이 시점에서, 아톰 보유자들은 무엇을 해야될까요?
아톰 보유자는 메인넷에서 본인의 아톰을 검증인에게 위임하고 거버넌스 프로포절에 투표를 할 수 있는 권리를 가질 수 있게 됩니다. 어떻게 보면 위임자들의 선택이 코스모스 네트워크의 성공을 좌우할 수 있다고 볼 수 있습니다. 단, 런칭 초기 아톰 송금 기능은 프로토콜 레벨에서 비활성화될 계획이며, 추후 하드포크를 통해 활성화될 것입니다.
**📒 안전하게 아톰을 위임하기 원하는 아톰 보유자들은 다음 가이드라인을 숙지하시고 따르시기 바랍니다. 본인의 안전을 위해서 [CLI 사용법](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/gaia/delegator-guide-cli.md)을 충분히 숙지하기 전에는 별도의 행동을 하시지 않는 것을 추천해 드립니다.**
안전하게 아톰을 위임하는 방법은 이 가이드에 설명된 것 외에는 없습니다. 현재로써 `gaiacli` 외 보안 감사를 거친 월렛 소프트웨어는 없습니다. 다른 월렛은 보안 감사를 시작하지 않은 상태입니다.
추가로 아톰을 위임하는 행위에는 매우 큰 리스크가 존재한다는 점을 인지하셔야 합니다. 한번 검증인에게 위임된 아톰은 일정 기간동안 묶이게 되며, 이 스테이킹 기간 동안 검증인의 실수로 슬래싱(아톰 삭감)이 발생하는 경우 위임자의 아톰 또한 함께 삭감될 수 있습니다. 검증인들에 대한 충분한 정보를 미리 확인하고 위임을 진행하는 것은 각 위임자의 책임입니다.
**코스모스 허브는 매우 실험적인 소프트웨어입니다. 메인넷 초기에는 다수의 문제, 업데이트 그리고 버그가 존재할 수 있습니다. 현재 제공되는 도구를 사용하는데에는 상당한 기술적 실력이 필요하며, 인터체인 재단과 텐더민트 팀의 컨트롤 밖에 있는 리스크가 존재합니다 (관련 리스크에 대한 자세한 정보는 인터체인 [코스모스 펀드레이저 약관](https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf)을 참고하세요). [아파치 2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0) 기반의 오픈 소스 소프트웨어를 사용함으로 발생하는 리스크는 본인의 책임이며, 어떠한 보증과 조건이 따르지 않습니다. 소프트웨어 사용으로 발생하는 문제에 대해서 인터체인 재단과 텐더민트는 책임을 지지 않습니다. 상당한 주의를 기울이며 신중하게 진행하시기 바랍니다.**
만약 위임 절차에 대한 질문이 있거나, 코스모스 개발자들과 대화를 나누고 싶으시다면 2월 14일에 열리는 온라인 밋업에 참가해주세요. 해당 밋업에서 런칭 때 아톰을 위임하는 절차를 한 단계씩 설명해 드릴 예정입니다.
등록 링크: [gotowebinar.com/register/](https://register.gotowebinar.com/register/5028753165739687691)
## 런칭을 위해 남은 마일스톤
🚦메인넷 런칭 프로세스를 확인하기 위해서는 다음 링크를 참고하세요: [cosmos.network/launch](https://cosmos.network/launch)
### 5: 코스모스 SDK 보안 감사 ✔
지난 1월, 코스모스 SDK는 다수의 외부 보안 감사 절차의 첫 단계를 진행했습니다. 보안 감사는 약 2주 반 기간에 걸려 진행되었습니다. 현재 두 개의 기관이 코스모스 SDK 코드를 검증한 상태이며, 다른 한 개 기관의 보안 감사가 진행 중입니다.
### 4: 코스모스 SDK 기능 동결 (feature freeze)
코스모스 SDK의 최종 주요 수정 사항은 [SDK v0.31.0 RC에](https://github.com/cosmos/cosmos-sdk/projects/27) 반영되었습니다. 해당 RC(Release candidate)가 완료된 후, 코스모스 SDK 팀은 추가적인 디버깅을 진행하여 런칭 전 보안성 확보를 위해 노력을 기울일 예정입니다.
코스모스 SDK v0.31.0이 릴리즈된 후, 혹시라도 발견되지 않은 버그를 검증하기 위해 Gaia 테스트넷을 추가로 진행할 계획입니다.
### 3: 게임 오브 스테이크 완료
지난 2018년 12월, 사상 최초의 경쟁적 테스트넷인 게임 오브 스테이크(GoS, Game of Stakes)가 시작되었습니다. GoS의 목표는 경제적 인센티브 검증, 지분증명으로 보안이 유지되는 블록체인의 사회적 요소를 검증하기 위해 진행되었습니다. 이후, GoS는 무려 3번의 하드 포크를 성공적으로 진행했습니다. GoS가 완료된 후, 점수 측정 기준을 기반으로 우승자를 발표하게 될 계획입니다.
### 2: 제네시스 트랜잭션 모으기
제네시스 시점에서 인터체인 재단은 아톰 분배 권고를 작성합니다. 여기에는 코스모스 펀드레이저 참가자, 초기 기여자, 게임 오브 스테이크 우승자 등이 포함됩니다. 아톰 분배 권고 목록에 포함된 인원은 `gentx`를 제출할 수 있으며, 제네시스 검증인이 되기 위해서 `gentx` 제출은 필수입니다. 이후 모든 `gentx` 파일이 모이게 되면 최종 제네시스 파일이 만들어집니다.
### 1: 코스모스 허브 메인넷 런칭 🔥 🚀 🌔🔥
+⅔의 보팅 파워가 온라인 상태가 되고, 커뮤니티가 제네시스 파일을 승인하게 된다면 코스모스 메인넷이 시작됩니다.
## 공식 코스모스 소통 채널
런칭 관련 소식을 전하는 공식 소통 채널은 다음과 같습니다:
* 코스모스 트위터 (twitter.com/cosmos)
* 코스모스 깃허브 (github.com/cosmos)
* 코스모스 블로그 (blog.cosmos.network)
또한 [코스모스 포럼](https://forum.cosmos.network/), [라이엇 그룹 채팅](https://riot.im/app/#/group/+cosmos:matrix.org) 그리고 [텔레그램 방](http://t.me/cosmosproject)은 코스모스의 공식적인 소식을 전달하는 채널이 아니라는 것을 인지하시기 바랍니다.
만약 앞으로 진행해야 하는 절차가 어렵거나 특정 정보의 소스를 확인할 수 없는 경우, 초기 시점에서 아무 행동을 하지 않고 위 3개의 공식 채널로 전달되는 업데이트를 확인하시기 바랍니다. 12개의 시드 단어를 그 어떤 단톡방 관리자, 웹사이트, 비공식 소프트웨어에 제공하지 마십시오.
**코스모스 팀은 절대로 개인적인 채널을 통해 프라이빗 키 또는 시드 단어를 요청하지 않습니다.**
## 메인넷 런칭때 안전할 수 있는 방법은?
런칭 시기가 다가오며 코스모스 허브 메인넷에 대한 기대감 또한 커지고 있습니다. 하지만 이런 시기를 틈타 일부는 본인의 이득을 위해 악의적이 행동을 할 확률 또한 높습니다. [사회 공학](https://terms.naver.com/entry.nhn?docId=863068&cid=42346&categoryId=42346) (social engineering)을 이용한 범죄는 인류 역사에서 꾸준히 있었으며, 오늘까지 [스피어피싱](https://terms.naver.com/entry.nhn?docId=3434661&cid=40942&categoryId=32828)과 [피싱 공격](https://terms.naver.com/entry.nhn?docId=3432525&cid=58445&categoryId=58445) 같은 일종의 범죄 수단으로 이어지고 있습니다.
약 성공한 공격의 95%는 스피어피싱과 피싱 공격으로 이루어졌으며, 이메일 외의 다수의 수단을 통해서도 일어나고 있습니다. 카카오톡, 텔레그램, 문자 메시지, 트위터 등 해커들의 공격 수단은 매우 다양하며, 개인의 자산과 개인 정보를 탈취하고 있습니다.
이런 공격을 대비하는 것은 벅차게 느껴질 수 있지만 몇 가지 유의 사항을 참고하신다면 공격의 위험을 크게 낮출 수 있습니다. 메인넷 런칭 준비에 관련해서는 다음 가이드라인이 보안적 리스크를 줄이고 정보를 검증하는데 도움이 될 수 있을 것입니다.
## 다음은 코스모스 메인넷 런칭 준비 유의사항입니다:
* 모든 소프트웨어는 공식 채널을 통해서만 다운로드를 하십시오. 또한, 12개 시드키가 입력될 수 있는 모든 작업은 최신 `gaiacli` 버전만을 사용하시기 바랍니다. 텐더민트, 코스모스 SDK 그리고 `gaiacli` 최신 버전은 공식 코스모스 깃허브를 통해서 배포됩니다. 공식 깃허브를 통해서 소프트웨어를 다운로드 함으로써 악의적으로 수정된 소프트웨어를 사용하는 것을 방지할 수 있습니다.
* 12개 시드 단어(시드 키)를 그 누구에게도 알려주지 마십시오. 시드 키는 오직 본인만이 관리해야 합니다. 특히 아톰 보관, 거래 등을 대행해주는 행위를 사칭하여 접근하는 사람들을 유의하십시오. 시드키를 안전하게 관리하기 위해서는 도난으로부터 안전한 오프라인 장소에 보관하시고, 혹시 모를 상황을 대비한 백업 수단을 유지하십시오. *시드키를 절대로 제삼자와 공유하지 마십시오.*
* 블록체인 또는 암호화폐 관련된 이메일과 웹사이트에서 다운로드를 유도하는 첨부 파일을 유의하십시오. 해커는 악의적으로 수정된 웹사이트를 통해서 컴퓨터 내에 있는 파일을 탈취할 수 있습니다. Gmail을 사용하신다면 흔히 사용되는 이메일 기반 피싱 공격을 다음 링크에서 확인하세요.
* 아톰 구매 시 충분한 검증을 진행하세요. 메인넷 런칭 초기에는 아톰 송금이 불가능 하므로, 송금 활성화가 되기 전에는 아톰 매수/매도가 불가능합니다. 또한 송금이 활성화된 후에도 매수/매도를 진행하는 거래소가 안전한지 확인을 하십시오.
* 텐더민트 팀 또는 인터체인 재단은 **절대로** 아톰을 팔지 않습니다. 만약 소셜 미디어 또는 이메일을 통한 토큰 세일 제안이 있다면, 해당 정보는 허위 정보입니다.
* 2단계 인증(2-factor authentication)을 활성화 하시고 주요 계정 복구 수단을 확인하십시오. 이메일, 소셜 미디어 계정, 깃허브 계정, 코스모스 포럼 계정 등은 공격자가 본인의 온라인 계정을 탈취할 수 있는 플랫폼을 제공합니다. 현재 2단계 인증을 사용하고 계시지 않는다면 활성화하시고 추가로 토큰 관리에 하드웨어 기반 키를 사용하시는 방법을 추천해 드립니다. 위 방법은 간단하지만 효율적으로 계정 탈취 가능성을 줄여줍니다.
* 포럼 또는 단톡방을 통해서 모르는 사람이 기술적 조언을 제공하는 것에 주의를 기울이십시오. 리스크가 높은 행동(토큰 전송, 키 입력 등)들의 명령어에 익숙해지시고 공식 문서를 참고하셔서 본인의 자산을 위험에 취할 수 있는 행동을 숙지하십시오. 코스모스 포럼, 라이엇 채팅 그리고 텔레그램 방은 공식 뉴스 제공 채널이 아니라는 점을 인지하십시오.
* 모든 송금 트랜잭션을 발생하기 전에 관련 정보를 확인하세요. 코스모스 주소는 길 수 있지만 4개 단어로 묶어서 확인하는 습관이 실수로 토큰을 소각하는 것을 방지할 수 있습니다.
만약 누군가 과도하게 좋은 조건으로 코스모스 관련 서비스를 제공한다면 우선 의심을 하시는 것을 추천합니다. 주요 정보는 그 어떤 상황에서도 외부인과 공유하면 안 됩니다. 또한 모든 정보를 공식 채널들을 통해 확인하십시오.
코스모스 팀, 텐더민트 팀 그리고 인터체인 팀은 개인 정보를 요청하거나 12개 시드키를 요구하는 이메일을 보내지 않습니다. 코스모스 팀은 언제나 공식 블로그, 트위터 그리고 깃허브를 통해서만 소통을 진행합니다.
#### Thank you to Cosmos Korea!
* 텔레그램: https://t.me/cosmoskr
* 페이스북 : https://facebook.com/groups/cosmoskorea
참고: 이 글은 정보 제공을 위하여 번역된 글입니다. 내용/해석에 차이가 있을 수 있으며, 이 경우 영문 원문이 상위 권한을 가집니다.

116
docs/cosmos-hub/launch/blog-2-cn.md
View File

@ -1,116 +0,0 @@
# **Cosmos主网上线三部曲**
Cosmos主网启动将分成3个阶段分布完成，下面我们将具体介绍每一阶段的预期目标。
## **🚨第一阶段：网络逐步趋于稳定🚨**
在第一阶段，主网可能会不太稳定，也许会出现暂停或其他故障，可能需要Cosmos主网验证人和全节点运营者们一起来协助修复。在网络趋于稳定过程中，出现此类故障并不意外。
**状态修改和主网启动:**
区块链的核心价值之一是其不可篡改性，也就是说我们不会通过回滚来修改过去的状态记录。最终，这种不可篡改的理念在软件共识协议层面得到了支持，并最终在社区参与者之间形成了社会契约。
也就是说，Cosmos Hub的底层技术开发是能够实现低难度的分叉和回滚的， 我们已经看到社区在测试网上做过多次相应的演练。这些技术也会在主网上应用，用以最终抵御卡特尔风险的发生。
回滚网络状态通常被认为是非常严重的问题，因为这将损害网络的经济最终性。因此，回滚网络状态只能在极端状态下使用，比如以太网的DAO硬分叉，也就是说，在Cosmos Hub主网启动初期，转账交易不会开启，因此回滚的危害性很小，因为状态转换远比“经济最终性”的影响低。 如果需要，比如发现漏洞，我们可以将过去某一个高度时的网络状态导出，然后重启网络，就如同我们在测试网上演练过的那样。
一旦链上治理决定开启交易功能，全网将会遵从经济最终性。
总而言之，如果在链上交易功能开启之前，Cosmos Hub发现任何错误或漏洞，那么用户可期望回滚至任意状态，甚至创世块。
一旦链上交易功能开始后，状态回滚方式将很难被采纳。
**对开发人员的建议**：Cosmos主网启动是投资者参与主网的第一阶段。作为分布式应用的开发人员，您可能是Cosmos-SDK框架或Tendermint Core的用户。开发者基于[Cosmos-SDK](https://cosmos.network/docs/)或[Tendermint](https://tendermint.com/docs/)的应用开发进度现阶段应该不受Cosmos Hub的影响，但如果您的项目需要使用[IBC](https://blog.cosmos.network/developer-deep-dive-cosmos-ibc-5855aaf183fe)（链间通信协议），则必须要等到第三阶段或参与即将开始的IBC测试网络。
**对于用户的建议**：在此阶段，我们强烈建议您不要交易Atoms（其实法律合同也限定不能交易），因为在这个阶段仍然存在状态回滚的风险。
但是，您可以通过下面链接的[CLI指南](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/gaia/delegator-guide-cli.md)和视频教程的指导，在此阶段将Atoms通证委托给验证人。当然，如果发生状态修改，那么所有收益（包括手续费和通胀收益）都将丢失。Voyager是用于与Cosmos Hub交互的图形化客户端，目前处于alpha版，正在持续开发中。一旦Voager beta版上线，并可以安全使用，我们将另行公告。
CLI指南和视频教程：https://v.qq.com/x/page/q08425izfhi.html
## 第二阶段：链上交易开启
**摘要：**
一旦我们认为主网足够稳定，在链上抵押了Atom的通证持有者将会通过链上治理过程投票决定是否开启链上交易。
Cosmos浏览器是查看治理提案状态的最佳途径，可以在我们的主网启动页面上找到多款[Cosmos浏览器](https://cosmos.network/launch)。
对用户来说：如果提案被社区接受，并且链上交易开启，您就可以在链上转移您的Atom了。
## 第三阶段：启用IBC协议
**摘要：**
第三阶段我们将会发布[IBC协议](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/spec/ibc/overview.md)，并且对是否将其纳入Cosmos-SDK的核心模块库进行链上治理投票。
**对开发人员的建议**：使用Cosmos-SDK或Tendermint BFT构建的应用专有链将能够连接到 Cosmos Hub，并与连接到Hubs上的其他任意区块链进行跨链交互。
**对用户的建议**：您可以将各种通证和NFT直接从采用IBC协议连接的一个链转移到另一个通过IBC协议连接的链，而无需通过一个第三方中心化平台。
## 验证人提示： 提交您的主网gentx文件
1. 验证人应该已经生成并且安全的保存好用于主网验证的共识密钥。
2. 验证人根据自己获得ATOM通证的来源，比如募资参与者或权益争夺活动的获奖者，准备好在创世文件（Genesis）中需要签署的交易。
3. 一旦创世通证分配计划发布，我们将开始征集gentx文件。
## 总结
Cosmos旨在建立所有区块链间的桥梁，最终建立一个区块链互联网。然而，路漫漫其修远兮，我们还有很长的路要走。主网上线之后，我们需要完成与整个通证经济世界的深度融合，很多的工作要做等着我们去完成。正如肯尼迪在逆境中曾经说过的那样：
“我们选择去月球，不是因为很容易，而是因为很难......”
走更崎岖的路，才会看见更美的风景！
****

67
docs/cosmos-hub/launch/blog-2-en.md
View File

@ -1,67 +0,0 @@
# The 3 Phases of the Cosmos Hub Mainnet
## Post-Mainnet Development Roadmap & Expectations for Users
The launch of the Cosmos Hub mainnet is expected to happen in phases. Here we outline what to expect in each phase.
# 🚨Phase I: Network Gains Stability 🚨
In the first phase, the network is likely to be unstable; it may experience halts or other forms of failure requiring intervention and coordination among Cosmos Hub validators and full node operators to deploy a fix. This type of failure is not unexpected while the network gains stability.
## State Reversions and Mainnet launch
One of the core ideologies around blockchains is immutability. This is the idea that we don't go
back and edit past state transitions. While this notion of immutability is implemented directly via consensus protocols in the software, it is ultimately upheld by social contract among participants.
That said, the technology underlying the Cosmos Hub was intentionally developed to enable low-friction forks and rollbacks. We’ve seen the community practice these techniques numerous times on the test networks. It’s likely they will need to be used on a mainnet as well. Ultimately, they are a countervailing force to the risk of cartel takeover.
Reverting state is often seen as highly grievous, as it compromises the network’s economic finality. Hence it should only be used in extreme conditions, as witnessed in the case of Ethereum with the DAO Hard Fork. That said, in the early days of the Cosmos Hub network, transfers will not be active, and hence the severity of state reversions will be reduced, as state transitions will be much less “economically final”. If necessary in case of bugs, the state can be exported from a past height and the network restarted, as practiced on the testnets.
Once governance chooses to enable transfers, the importance of economic finality must be respected by the network.
To summarize, if there are errors or vulnerabilities in the Cosmos Hub in the days before transfers are enabled, users should expect arbitrary state rollbacks even to genesis.
Once transfers are enabled, state rollbacks will be much more difficult to justify.
**What this means for developers:** The Cosmos mainnet launch is the first phase in which fundraiser participants will be working together to operate the software. As a decentralized application developer, you are likely a user of either the [Cosmos-SDK framework](https://cosmos.network/docs/) or [Tendermint Core](https://tendermint.com/docs/). The progress of your Cosmos-SDK or Tendermint-based application should be independent of the Cosmos Hub roadmap. However, if your project requires the use of [Inter-Blockchain Communication][blog post], you must wait until Phase III, or participate in the IBC testnets that will begin shortly.
**What this means for users:** In this phase, we strongly recommend that you do not arrange to trade Atoms (eg. by legal contract as they will not be transferable yet) as there is the risk of state being reverted.
You can, however, safely delegate Atoms to validators in this phase by following the CLI guideline and video tutorial linked below. Of course, in the event of a state reversion, any earned fees and inflation may be lost. Note that only `gaiacli` should be used for making transactions. Voyager, the GUI for interacting with the Cosmos Hub, is currently in alpha and undergoing development. A separate announcement will be made once Voyager is safer for use.
CLI Guide 🔗: [github.com/cosmos/cosmos-sdk/…/delegator-guide-cli.md](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/gaia/delegator-guide-cli.md)
**Watch CLI delegation tutorial:** [Cosmos YouTube](https://www.youtube.com/watch?v=ydZw6o6Mzy0)
# Phase II: Transfers Enabled
**Summary:** Once mainnet is deemed sufficiently stable, bonded Atom holders will vote to decide whether or not Atom transfers should be enabled. This procedure will happen through on-chain governance.
The best way to check on the status of governance proposals is to view them through Cosmos explorers. A list of explorers can be found on the launch page: [cosmos.network/launch](https://cosmos.network/launch).
**What this means for users:** If the proposal is accepted and transfers are enabled, then it becomes possible to transfer Atoms.
# Phase III: IBC Enabled
**Summary:** In Phase III, the [IBC protocol][ibc] is released and Atom holders vote via on-chain governance on whether or not to enable it as part of the core module library within the Cosmos-SDK.
**What this means for developers:** Application-specific blockchains that are built using the Cosmos-SDK or Tendermint BFT will be able to connect to the Hub and interoperate/compose with all of the other blockchains that are connected to it.
**What this means for users:** You will be able to transfer various tokens and NFTs directly from one IBC-connected chain to another IBC-connected chain without going through a centralized
third-party platform.
# Housekeeping for Validators: Submitting a `gentx` for mainnet
1. You should have generated and secured the validator consensus key you are going to be validating under during mainnet.
2. Be prepared to sign a transaction under an address in the genesis file either from the fundraiser or Game of Stakes depending on where you received your ATOM allocation.
3. We will begin collecting Gentxs for mainnet once the recommended genesis allocations are published.
# In Closing
The Cosmos mission is to build bridges to connect all blockchains—to build an Internet of Blockchains. Clearly, we have a long road of development ahead of us. And after mainnet, the real work to a world of deeply integrated token economies is still ahead of us. But as John Fitzgerald Kennedy once said in the face of adversity:
*“We choose to go to the moon...not because they are easy, but because they are hard….”*
To the Moon 🚀
[blog post]: [https://blog.cosmos.network/developer-deep-dive-cosmos-ibc-5855aaf183fe]
[ibc]: [https://github.com/cosmos/cosmos-sdk/blob/develop/docs/spec/ibc/overview.md]

74
docs/cosmos-hub/launch/blog-2-kr.md
View File

@ -1,74 +0,0 @@
# 코스모스 허브 메인넷의 세 가지 단계
## 메인넷 후 개발 로드맵과 유저들을 위한 필수 정보
코스모스 허브의 런칭은 단계별로 나뉘어 진행될 계획입니다. 다음은 각 단계별로 어떤 사항들이 진행될지에 대한 요약입니다.
# 🚨1단계: 네트워크 안정성 확보 🚨
메인넷의 최초 단계인 1단계에서 코스모스 네트워크는 다소 불안정할 수 있습니다. 메인넷 초기에는 네트워크 중단 같은 문제들이 발생할 확률이 존재합니다.
혹시라도 발생할 수 있는 문제들을 해결하기 위해서는 코스모스 허브 검증인 간, 풀노드 운영자 등 참여자들 간의 긴밀한 협업이 필요합니다.
유저는 충분한 네트워크 안정성이 확보될 때까지 문제들이 발생할 수 있다는 것을 인지해야 합니다.
**블록체인 롤백과 메인넷 런칭**
블록체인 기술의 핵심 이념 중 하나는 불가역성(immutability)입니다.
불가역성이란 이미 진행된 블록체인의 기록을 되돌아가 바꾸지 않는다는 것입니다. 블록체인의 불가역성은 소프트웨어 계층에서 합의 프로토콜의 형태로 전개되지만, 궁극적으로 네트워크 참여자들의 사회적 계약(social contract) 형태로 유지됩니다.
여기서 참고할 것은 코스모스 허브는 의도적으로 포크와 롤백 절차를 간소화할 수 있도록 설계되었다는 것입니다. 코스모스 커뮤니티는 테스트넷 단계에서 이런 기능을 실제 사용했으며, 메인넷에서 또한 사용될 수 있습니다. 포크와 롤백 기능은 특정 카르텔 집단이 네트워크를 점령하는 것에 대한 대응 도구로 사용될 수 있습니다.
대다수의 블록체인 커뮤니티는 롤백을 부정적으로 인식하고 있으며 매우 신중하게 결정되어야 합니다. 블록체인의 상태를 되돌린다는 것은 블록체인 네트워크의 경제적 완결성(economic finality)을 깨트리는 행동입니다. 그렇기 때문에 블록체인 롤백은 이더리움의 The DAO 하드포크 같은 극한 상황 상황에서만 사용되어야 합니다.
단, 코스모스 허브 네트워크의 초기 단계에서는 토큰 전송 기능이 비활성화된 상태로 시작됩니다. 이런 특성은 블록체인 롤백의 중대성을 줄이게 되며 블록체인 상태의 변경의 ‘경제적 완결성’을 낮추게 됩니다. 버그 등 문제 발생으로 블록체인 롤백이 필요하다는 판단이 내려지는 경우, 테스트넷과 같이 블록체인 상태 롤백이 제네시스 블록까지도 진행될 수 있습니다.
거버넌스에 의하여 토큰 전송이 활성화되는 경우, 코스모스 네트워크는 경제적 완결성을 따르게 됩니다.
위 내용을 요약하자면, 토큰 전송이 활성화되기 전 코스모스 허브에 에러 또는 취약점이 발견되는 경우, 블록체인의 (제네시스 상태까지) 롤백이 진행될 수 있습니다.
하지만 토큰 전송이 활성화된 뒤라면 블록체인 롤백을 정당화하는 것은 상당히 어렵게 됩니다.
**개발자 참고 사항**: 코스모스 메인넷 런칭은 펀드레이저 참가자들이 협동하여 코스모스 허브 소프트웨어를 운영하는 첫 단계입니다. 생태계 내 대다수의 탈중앙화 애플리케이션 개발자는 [코스모스 SDK](https://cosmos.network/docs/) 또는 [텐더민트 코어](https://tendermint.com/docs/)를 사용하고 있는 것으로 예상됩니다. 각 코스모스 SDK/텐더민트 기반 애플리케이션의 개발 진행은 코스모스 허브와 별도로 진행되어도 무관합니다. 다만, [IBC](https://blog.cosmos.network/developer-deep-dive-cosmos-ibc-5855aaf183fe)(Inter-Blockchain Communication)을 사용하기 위해서는 메인넷 3단계까지 기다리거나 IBC 테스트넷에서 시범운영을 하실 수 있습니다.
**유저 참고 사항**: 메인넷 최초 단계에서는 코스모스 아톰을 거래하지 **않는** 것을 강력하게 권고합니다 (예, 법적 계약을 통한 거래). 1단계에서는 제네시스 블록까지 긴급 롤백이 진행될 수 있으므로 트랜잭션이 번복될 수 있는 위험이 존재합니다.
다만, 유저는 CLI 가이드 또는 하단의 영상 투토리얼을 참고하여 안전하게 아톰 위임을 진행하실 수는 있습니다. 다만 만약 블록체인 롤백이 진행되는 경우, 스테이킹으로 받은 리워드와 인플레이션 리워드의 손실이 있습니다.
첫 단계에서 오직 CLI를 사용해서 트랜잭션을 발생하는 것을 코스모스 허브와 소통할 때 사용될 보이저(Voyager) 지갑은 현재 알파 단계에 있기 때문에 안전하게 사용할 수 있는 프로그램은 CLI 뿐이라는 것을 강조합니다. 보이저 지갑이 안전하다는 판단이 내려지고 베타가 시작될때 별도의 공지가 있겠습니다.
CLI 가이드 🔗: [https://github.com/cosmos/cosmos-sdk/blob/develop/docs/translations/kr/gaia/delegator-guide-cli.md](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/translations/kr/gaia/delegator-guide-cli.md)
CLI 위임 투토리얼 (영어): [https://www.youtube.com/watch?v=ydZw6o6Mzy0](https://www.youtube.com/watch?v=ydZw6o6Mzy0)
# 2단계: 토큰 전송 활성화
**요약**: 메인넷이 충분히 안정성을 확보했다는 판단이 내려진 후, 위임된 아톰을 보유한 홀더들은 아톰 토큰 전송 활성화에 대한 프로포절에 투표를 할 수 있습니다. 해당 절차는 블록체인 상의 거버넌스 절차를 통해 진행됩니다.
거버넌스 프로포절 현황에 대한 정보는 다양한 코스모스 익스플로러를 통해 확인하실 수 있습니다. 코스모스 익스플로러 목록은 [여기](https://cosmos.network/launch)를 참고하세요.
**유저 참고 사항**: 토큰 전송 활성화 프로포절이 통과하고 전송이 활성화된 후 아톰 이동이 가능해집니다.
# 3단계: IBC 활성화
**요약**: 3단계에서는 IBC 프로토콜이 공개됩니다. 토큰 홀더는 IBC 기능을 코스모스 SDK의 코어 모듈 라이브러리로 활성화할지에 대한 거버넌스 투표를 하게됩니다.
**개발자 참고 사항**: 이 단계에서 코스모스 SDK/텐더민트 BFT를 기반으로 만들어진 애플리케이션 특화 블록체인(application-specific blockchain)은 IBC를 통해 중앙화된 제삼자 없이 코스모스 허브와 소통할 수 있게 됩니다. IBC를 이용해 블록체인 간 다양한 토큰과 NFT(Non-fungible token)들의 이동이 가능해집니다.
# 메인넷 검증인 준비 사항
1. 메인넷에서 사용할 검증인 컨센서스 키(validator consensus key)를 생성하고 안전한 형태로 보관하십시오.
2. 게임 오브 스테이크 상금 / 펀드레이저 계정에서 트랜잭션 생성 및 서명을 할 수 있도록 준비하십시오
3. ICF의 제네시스 토큰 분배 제안이 공개된 후 메인넷 Gentx 수집 작업을 시작합니다.
# 글을 마무리 하며
코스모스의 목적은 모든 블록체인을 연결하여 ‘블록체인의 인터넷’을 만드는 것입니다.
앞으로 가야 할 길이 멀다는 것을 알고 있습니다.
메인넷이 런칭된 후, 토큰 이코노미 기반의 세상을 설계하는 본격적인 일이 본격적으로 시작돼야 할 것입니다.
하지만 미국 전 대통령 존 케네디의 말을 인용하자면, “우리는 달에 가기로 결정하였습니다. 그것이 쉽기 때문이 아니라 어렵기 때문에 이렇게 결정한 것입니다.”
달에 도착하는 그 날까지… 🚀

185
docs/cosmos-hub/ledger.md
View File

@ -1,185 +0,0 @@
# Ledger Nano Support
Using a hardware wallet to store your keys greatly improves the security of your crypto assets. The Ledger device acts as an enclave of the seed and private keys, and the process of signing transaction takes place within it. No private information ever leaves the Ledger device. The following is a short tutorial on using the Cosmos Ledger app with the Gaia CLI or the [Lunie.io](https://lunie.io/#/) web wallet.
At the core of a Ledger device there is a mnemonic seed phrase that is used to generate private keys. This phrase is generated when you initialize you Ledger. The mnemonic is compatible with Cosmos and can be used to seed new accounts.
::: danger
Do not lose or share your 24 words with anyone. To prevent theft or loss of funds, it is best to keep multiple copies of your mnemonic stored in safe, secure places. If someone is able to gain access to your mnemonic, they will fully control the accounts associated with them.
:::
## Gaia CLI + Ledger Nano
The tool used to generate addresses and transactions on the Cosmos Hub network is `gaiacli`. Here is how to get started. If using a CLI tool is unfamiliar to you, scroll down and follow instructions for using the Lunie.io web wallet instead.
### Before you Begin
- [Install the Cosmos app onto your Ledger](https://github.com/cosmos/ledger-cosmos/blob/master/README.md#installing)
- [Install Golang](https://golang.org/doc/install)
- [Install Gaia](https://cosmos.network/docs/cosmos-hub/installation.html)
Verify that gaiacli is installed correctly with the following command
```bash
gaiacli version --long
➜ cosmos-sdk: 0.34.3
git commit: 67ab0b1e1d1e5b898c8cbdede35ad5196dba01b2
vendor hash: 0341b356ad7168074391ca7507f40b050e667722
build tags: netgo ledger
go version go1.11.5 darwin/amd64
```
### Add your Ledger key
- Connect and unlock your Ledger device.
- Open the Cosmos app on your Ledger.
- Create an account in gaiacli from your ledger key.
::: tip
Be sure to change the _keyName_ parameter to be a meaningful name. The `ledger` flag tells `gaiacli` to use your Ledger to seed the account.
:::
```bash
gaiacli keys add <keyName> --ledger
➜ NAME: TYPE: ADDRESS: PUBKEY:
<keyName> ledger cosmos1... cosmospub1...
```
Cosmos uses [HD Wallets](./hd-wallets.md). This means you can setup many accounts using the same Ledger seed. To create another account from your Ledger device, run;
```bash
gaiacli keys add <secondKeyName> --ledger
```
### Confirm your address
Run this command to display your address on the device. Use the `keyName` you gave your ledger key. The `-d` flag is supported in version `1.5.0` and higher.
```bash
gaiacli keys show <keyName> -d
```
Confirm that the address displayed on the device matches that displayed when you added the key.
### Connect to a full node
Next, you need to configure gaiacli with the URL of a Cosmos full node and the appropriate `chain_id`. In this example we connect to the public load balanced full node operated by Chorus One on the `cosmoshub-2` chain. But you can point your `gaiacli` to any Cosmos full node. Be sure that the `chain_id` is set to the same chain as the full node.
```bash
gaiacli config node https://cosmos.chorus.one:26657
gaiacli config chain_id cosmoshub-2
```
Test your connection with a query such as:
``` bash
`gaiacli query staking validators`
```
::: tip
To run your own full node locally [read more here.](https://cosmos.network/docs/cosmos-hub/join-mainnet.html#setting-up-a-new-node).
:::
### Sign a transaction
You are now ready to start signing and sending transactions. Send a transaction with gaiacli using the `tx send` command.
``` bash
gaiacli tx send --help # to see all available options.
```
::: tip
Be sure to unlock your device with the PIN and open the Cosmos app before trying to run these commands
:::
Use the `keyName` you set for your Ledger key and gaia will connect with the Cosmos Ledger app to then sign your transaction.
```bash
gaiacli tx send <keyName> <destinationAddress> <amount><denomination>
```
When prompted with `confirm transaction before signing`, Answer `Y`.
Next you will be prompted to review and approve the transaction on your Ledger device. Be sure to inspect the transaction JSON displayed on the screen. You can scroll through each field and each message. Scroll down to read more about the data fields of a standard transaction object.
Now, you are all set to start [sending transactions on the network](./delegator-guide-cli.md#sending-transactions).
### Receive funds
To receive funds to the Cosmos account on your Ledger device, retrieve the address for your Ledger account (the ones with `TYPE ledger`) with this command:
```bash
gaiacli keys list
➜ NAME: TYPE: ADDRESS: PUBKEY:
<keyName> ledger cosmos1... cosmospub1...
```
### Further documentation
Not sure what `gaiacli` can do? Simply run the command without arguments to output documentation for the commands in supports.
::: tip
The `gaiacli` help commands are nested. So `$ gaiacli` will output docs for the top level commands (status, config, query, and tx). You can access documentation for sub commands with further help commands.
For example, to print the `query` commands:
```bash
gaiacli query --help
```
Or to print the `tx` (transaction) commands:
```bash
gaiacli tx --help
```
:::
# Lunie.io
The Lunie web wallet supports signing with Ledger Nano S. Here is a short intro to using your Ledger with [Lunie.io](https://lunie.io).
### Connect your device
- Connect your Ledger device to your computer, unlock it with the PIN and open the Cosmos app.
- Open [https://lunie.io](https://lunie.io) in your web browser (latest version of Google Chrome preferred)
- Click “Sign in”.
- Choose “Sign in with Ledger Nano S”
### Confirm your address
Run this command to display your address on the device. Use the `keyName` you gave your ledger key. The `-d` flag is supported in version `1.5.0` and higher.
```bash
gaiacli keys show <keyName> -d
```
Confirm that the address displayed on your Ledger matches that shown on Lunie.io before proceeding.
Now you can use your Ledger key to sign transctions on Lunie.
To learn more about using Lunie, [here is a tutorial](https://medium.com/easy2stake/how-to-delegate-re-delegate-un-delegate-cosmos-atoms-with-the-lunie-web-wallet-eb72369e52db) on staking and delegating ATOMs using the Lunie web wallet.
# The Cosmos Standard Transaction
Transactions in Cosmos embed the [Standard Transaction type](https://godoc.org/github.com/cosmos/cosmos-sdk/x/auth#StdTx) from the Cosmos SDK. The Ledger device displays a serialized JSON representation of this object for you to review before signing the transaction. Here are the fields and what they mean:
- `chain-id`: The chain to which you are broadcasting the tx, such as the `gaia-13003` testnet or `cosmoshub-2`: mainnet.
- `account_number`: The global id of the sending account assigned when the account receives funds for the first time.
- `sequence`: The nonce for this account, incremented with each transaction.
- `fee`: JSON object describing the transaction fee, its gas amount and coin denomination
- `memo`: optional text field used in various ways to tag transactions.
- `msgs_<index>/<field>`: The array of messages included in the transaction. Double click to drill down into nested fields of the JSON.
# Support
For further support, start by looking over the posts in our [forum](https://forum.cosmos.network/search?q=ledger)
Feel welcome to reach out in our [Telegram channel](https://t.me/cosmosproject) to ask for help.
Here are a few relevant and helpful tutorials from the wonderful Cosmos community:
- [Ztake](https://medium.com/@miranugumanova) - [How to Redelegate Cosmos Atoms with the Lunie Web Wallet](https://medium.com/@miranugumanova/how-to-re-delegate-cosmos-atoms-with-lunie-web-wallet-8303752832c5)
- [Cryptium Labs](https://medium.com/cryptium-cosmos) - [How to store your ATOMS on your Ledger and delegate with the command line](https://medium.com/cryptium-cosmos/how-to-store-your-cosmos-atoms-on-your-ledger-and-delegate-with-the-command-line-929eb29705f)

82
docs/cosmos-hub/reproducible-builds.md
View File

@ -1,82 +0,0 @@
## Build Gaia Deterministically
Gitian is the deterministic build process that is used to build the Gaia executables. It provides a way to be reasonably sure that the executables are really built from the git source. It also makes sure that the same, tested dependencies are used and statically built into the executable.
Multiple developers build the source code by following a specific descriptor ("recipe"), cryptographically sign the result, and upload the resulting signature. These results are compared and only if they match, the build is accepted and provided for download.
More independent Gitian builders are needed, which is why this guide exists. It is preferred you follow these steps yourself instead of using someone else's VM image to avoid 'contaminating' the build.
This page contains all instructions required to build and sign reproducible Gaia binaries for Linux, Mac OS X, and Windows.
## Prerequisites
Make sure your system satisfy minimum requisites as outlined in https://github.com/devrandom/gitian-builder#prerequisites.
All the following instructions have been tested on *Ubuntu 18.04.2 LTS* with *docker 18.06.1-ce* and *docker 18.09.6-ce*.
If you are on Mac OS X, make sure you have prepended your `PATH` environment variable with GNU coreutils's path before running the build script:
```
export PATH=/usr/local/opt/coreutils/libexec/gnubin/:$PATH
```
## Build and sign
Clone cosmos-sdk:
```
git clone git@github.com:cosmos/cosmos-sdk
```
Checkout the commit, branch, or release tag you want to build:
```
cd cosmos-sdk/
git checkout v0.35.0
```
Run the following command to launch a build for `linux` and sign the final build
report (replace `user@example.com` with the GPG identity you want to sign the report with):
```
./cmd/gaia/contrib/gitian-build.sh -s user@example.com linux
```
The above command generates two directories in the current working directory:
* `gitian-build-linux` containing the `gitian-builder` clone used to drive the build process.
* `gaia.sigs` containing the signed build report.
Replace `linux` in the above command with `darwin` or `windows` to run builds for Mac OS X and Windows respectively.
Run the following command to build binaries for all platforms (`darwin`, `linux`, and `windows`):
```
cd cosmos-sdk/
for platform in darwin linux windows; do ./cmd/gaia/contrib/gitian-build.sh -s user@example.com $platform `pwd`; done
```
If you want to generate unsigned builds, just remove the option `-s` from the command line:
```
./cmd/gaia/contrib/gitian-build.sh linux
```
At the end of the procedure, build results can be found in the `./gaia.sigs` directory:
Please refer to the `cmd/gaia/contrib/gitian-build.sh`'s help screen for further information on its usage.
## Signatures upload
Once signatures are generated, they could be uploaded to gaia's dedicated repository: https://github.com/cosmos/gaia.sigs.
## Troubleshooting
### Docker gitian-target container cannot be killed
The issue is due to a relatively recent kernel apparmor change, [see here](https://github.com/moby/moby/issues/36809#issuecomment-379325713) for more information on a potential mitigation for the issue.
On Ubuntu 18.04, when the container hangs and `docker` is unable to kill it you can try to use `pkill` to forcibly terminate `containerd-shim`:
```
sudo pkill containerd-shim
docker system prune
```

93
docs/cosmos-hub/upgrade-node.md
View File

@ -1,93 +0,0 @@
# Upgrade Your Node
This document describes the upgrade procedure of a `gaiad` full-node to a new version.
## Software Upgrade
First, stop your instance of `gaiad`. Next, upgrade the software:
```bash
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
git fetch --all && git checkout <new_version>
make tools install
```
::: tip
*NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
:::
See the [testnet repo](https://github.com/cosmos/testnets) for details on which version is needed for which public testnet, and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases) for details on each release.
Your full node has been cleanly upgraded!
## Ugrade Genesis File
:::warning
If the new version you are upgrading to has breaking changes, you will have to restart your chain. If it is not breaking, you can skip to [Restart](#restart)
:::
To upgrade the genesis file, you can either fetch it from a trusted source or export it locally.
### Fetching from a Trusted Source
If you are joining the mainnet, fetch the genesis from the [mainnet repo](https://github.com/cosmos/launc). If you are joining a public testnet, fetch the genesis from the appropriate testnet in the [testnet repo](https://github.com/cosmos/testnets). Otherwise, fetch it from your trusted source.
Save the new genesis as `new_genesis.json`. Then replace the old `genesis.json` with `new_genesis.json`
```bash
cd $HOME/.gaiad/config
cp -f genesis.json new-_enesis.json
mv new_genesis.json genesis.json
```
Then, go to the [reset data](#reset-data) section.
### Exporting State to a New Genesis Locally
If you were running a node in the previous version of the network and want to build your new genesis locally from a state of this previous network, use the following command:
```bash
cd $HOME/.gaiad/config
gaiad export --for-zero-height --height=<export-height> > new_genesis.json
```
The command above take a state at a certain height `<export-height>` and turns it into a new genesis file that can be used to start a new network.
Then, replace the old `genesis.json` with `new_genesis.json`.
```bash
cp -f genesis.json new-_enesis.json
mv new_genesis.json genesis.json
```
At this point, you might want to run a script to update the exported genesis into a genesis that is compatible with your new version. For example, the attributes of a the `Account` type changed, a script should query encoded account from the account store, unmarshall them, update their type, re-marshal and re-store them. You can find an example of such script [here](https://github.com/cosmos/cosmos-sdk/blob/develop/contrib/export/v0.33.x-to-v0.34.0.py).
## 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 it is not breaking, you can skip to [Restart](#restart)
:::
::: warning
If you are running a **validator node** on the mainnet, always be careful when doing `gaiad unsafe-reset-all`. You should never use this command if you are not switching `chain-id`.
:::
::: danger IMPORTANT
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 get slashed due to double sign !
:::
First, remove the outdated files and reset the data. **If you are running a validator node, make sure you understand what you are doing before resetting**.
```bash
gaiad unsafe-reset-all
```
Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.
## Restart
To restart your node, just type:
```bash
gaiad start
```

34
docs/cosmos-hub/validators/kms/kms.md
View File

@ -1,34 +0,0 @@
# KMS - Key Management System
[Tendermint KMS](https://github.com/tendermint/kms) 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/tendermint/kms#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 in various ways:
### Using a YubiHSM
Detailed information on how to setup a KMS with YubiHSM2 can be found [here](https://github.com/tendermint/kms/blob/master/README.yubihsm.md)
### Using a Ledger device running the Tendermint app
Detailed information on how to setup a KMS with Ledger Tendermint App can be found [here](kms_ledger.md)

113
docs/cosmos-hub/validators/kms/kms_ledger.md
View File

@ -1,113 +0,0 @@
# Setting up Tendermint KMS + Ledger
::: danger Warning
The following instructions are a brief walkthrough and not a comprehensive guideline. You should consider and [research more about the security implications](./security.md) of activating an external KMS.
:::
::: danger Warning
KMS and Ledger Tendermint app are currently work in progress. Details may vary. Use with care under your own risk.
:::
## Tendermint Validator app (for Ledger devices)
You should be able to find the Tendermint app in Ledger Live.
*Note: at the moment, you might need to enable `developer mode` in Ledger Live settings*
## KMS configuration
In this section, we will configure a KMS to use a Ledger device running the Tendermint Validator App.
### Config file
You can find other configuration examples [here](https://github.com/tendermint/kms/blob/master/tmkms.toml.example)
- Create a `~/.tmkms/tmkms.toml` file with the following content (use an adequate `chain_id`)
```toml
# Example KMS configuration file
[[validator]]
addr = "tcp://localhost:26658" # or "unix:///path/to/socket"
chain_id = "gaia-11001"
reconnect = true # true is the default
secret_key = "~/.tmkms/secret_connection.key"
[[providers.ledgertm]]
chain_ids = ["gaia-11001"]
```
- Edit `addr` to point to your `gaiad` instance.
- Adjust `chain-id` to match your `.gaiad/config/config.toml` settings.
- `provider.ledgertm` has not additional parameters at the moment, however, it is important that you keep that header to enable the feature.
*Plug your Ledger device and open the Tendermint validator app.*
### Generate secret key
Now you need to generate secret_key:
```bash
tmkms keygen ~/.tmkms/secret_connection.key
```
### Retrieve validator key
The last step is to retrieve the validator key that you will use in `gaiad`.
Start the KMS:
```bash
tmkms start -c ~/.tmkms/tmkms.toml
```
The output should look similar to:
```text
07:28:24 [INFO] tmkms 0.3.0 starting up...
07:28:24 [INFO] [keyring:ledgertm:ledgertm] added validator key cosmosvalconspub1zcjduepqy53m39prgp9dz3nz96kaav3el5e0th8ltwcf8cpavqdvpxgr5slsd6wz6f
07:28:24 [INFO] KMS node ID: 1BC12314E2E1C29015B66017A397F170C6ECDE4A
```
The KMS may complain that it cannot connect to gaiad. That is fine, we will fix it in the next section.
This output indicates the validator key linked to this particular device is: `cosmosvalconspub1zcjduepqy53m39prgp9dz3nz96kaav3el5e0th8ltwcf8cpavqdvpxgr5slsd6wz6f`
Take note of the validator pubkey that appears in your screen. *We will use it in the next section.*
## Gaia configuration
You need to enable KMS access by editing `.gaiad/config/config.toml`. In this file, modify `priv_validator_laddr` to create a listening address/port or a unix socket in `gaiad`.
For example:
```toml
...
# TCP or UNIX socket address for Tendermint to listen on for
# connections from an external PrivValidator process
priv_validator_laddr = "tcp://127.0.0.1:26658"
...
```
Let's assume that you have set up your validator account and called it `kmsval`. You can tell gaiad the key that we've got in the previous section.
```bash
gaiad gentx --name kmsval --pubkey {.ValidatorKey}
```
Now start `gaiad`. You should see that the KMS connects and receives a signature request.
Once the ledger receives the first message, it will ask for confirmation that the values are adequate.
![](ledger_1.jpg)
Click the right button, if the height and round are correct.
After that, you will see that the KMS will start forwarding all signature requests to the ledger:
![](ledger_2.jpg)
::: danger Warning
The word TEST in the second picture, second line appears because they were taken on a pre-release version.
Once the app as been released in Ledger's app store, this word should NOT appear.
:::

BIN
docs/cosmos-hub/validators/kms/ledger_1.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/cosmos-hub/validators/kms/ledger_2.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

34
docs/cosmos-hub/validators/overview.md
View File

@ -1,34 +0,0 @@
# Validators Overview
## Introduction
The [Cosmos Hub](/introduction/cosmos-hub.md) is based on [Tendermint](/introduction/tendermint.md), which relies on a set of validators that are responsible for committing new blocks in the blockchain. These validators participate in the consensus protocol by broadcasting votes which contain cryptographic signatures signed by each validator's private key.
Validator candidates can bond their own Atoms and have Atoms ["delegated"](/staking/delegators), or staked, to them by token holders. The Cosmos Hub will have 100 validators, but over time this will increase to 300 validators according to a predefined schedule. The validators are determined by who has the most stake delegated to them — the top 100 validator candidates with the most stake will become Cosmos validators.
Validators and their delegators will earn Atoms as block provisions and tokens as transaction fees through execution of the Tendermint consensus protocol. Initially, transaction fees will be paid in Atoms but in the future, any token in the Cosmos ecosystem will be valid as fee tender if it is whitelisted by governance. Note that validators can set commission on the fees their delegators receive as additional incentive.
If validators double sign, are frequently offline or do not participate in governance, their staked Atoms (including Atoms of users that delegated to them) can be slashed. The penalty depends on the severity of the violation.
## Hardware
There currently exists no appropriate cloud solution for validator key management. This may change in 2018 when cloud SGX becomes more widely available. For this reason, validators must set up a physical operation secured with restricted access. A good starting place, for example, would be co-locating in secure data centers.
Validators should expect to equip their datacenter location with redundant power, connectivity, and storage backups. Expect to have several redundant networking boxes for fiber, firewall and switching and then small servers with redundant hard drive and failover. Hardware can be on the low end of datacenter gear to start out with.
We anticipate that network requirements will be low initially. The current testnet requires minimal resources. Then bandwidth, CPU and memory requirements will rise as the network grows. Large hard drives are recommended for storing years of blockchain history.
## Set Up a Website
Set up a dedicated validator's website and signal your intention to become a validator on our [forum](https://forum.cosmos.network/t/validator-candidates-websites/127/3). This is important since delegators will want to have information about the entity they are delegating their Atoms to.
## Seek Legal Advice
Seek legal advice if you intend to run a Validator.
## Community
Discuss the finer details of being a validator on our community chat and forum:
* [Validator Chat](https://riot.im/app/#/room/#cosmos_validators:matrix.org)
* [Validator Forum](https://forum.cosmos.network/c/validating)

56
docs/cosmos-hub/validators/security.md
View File

@ -1,56 +0,0 @@
## Validator Security
Each validator candidate is encouraged to run its operations independently, as diverse setups increase the resilience of the network. Validator candidates should commence their setup phase now in order to be on time for launch.
## Key Management - HSM
It is mission critical that an attacker cannot steal a validator's key. If this is possible, it puts the entire stake delegated to the compromised validator at risk. Hardware security modules are an important strategy for mitigating this risk.
HSM modules must support `ed25519` signatures for the hub. The YubiHSM2 supports `ed25519` and we expect to have an adapter library available in December 2017. The YubiHSM can protect a private key but cannot ensure in a secure setting that it won't sign the same block twice.
The Tendermint team is also working on extending our Ledger Nano S application to support validator signing. This app can store recent blocks and mitigate double signing attacks.
We will update this page when more key storage solutions become available.
## Sentry Nodes (DDOS Protection)
Validators are responsible for ensuring that the network can sustain denial of service attacks.
One recommended way to mitigate these risks is for validators to carefully structure their network topology in a so-called sentry node architecture.
Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. A validator node will typically run in a data center. Most data centers provide direct links the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones.
Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network.
To setup your sentry node architecture you can follow the instructions below:
Validators nodes should edit their config.toml:
```bash
# Comma separated list of nodes to keep persistent connections to
# Do not add private peers to this list if you don't want them advertised
persistent_peers =[list of sentry nodes]
# Set true to enable the peer-exchange reactor
pex = false
```
Sentry Nodes should edit their config.toml:
```bash
# Comma separated list of peer IDs to keep private (will not be gossiped to other peers)
# 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:
- `GA` (for Gaia flags)
- `TM` (for Tendermint flags)
- `BC` (for democli or basecli flags)
For example, the environment variable `GA_CHAIN_ID` will map to the command line flag `--chain-id`. Note that while explicit command-line flags will take precedence over environment variables, environment variables will take precedence over any of your configuration files. For this reason, it's imperative that you lock down your environment such that any critical parameters are defined as flags on the CLI or prevent modification of any environment variables.

296
docs/cosmos-hub/validators/validator-faq.md
View File

@ -1,296 +0,0 @@
# Validator FAQ
::: warning Disclaimer
This is work in progress. Mechanisms and values are susceptible to change.
:::
## General Concepts
### What is a validator?
The [Cosmos Hub](../what-is-gaia.md) 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'?
The Cosmos Hub is a public Proof-Of-Stake (PoS) blockchain, meaning that the weight of validators is determined by the amount of staking tokens (Atoms) bonded as collateral. These Atoms 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 100 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 Atoms 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://cosmos.network/resources/delegators).
## 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 Atoms 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 Atoms bonded by delegators and Atoms self-bonded by the entity which designated themselves.
Out of all validator candidates that signaled themselves, the 100 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 100 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 will increase, according to the following schedule (*Note: this schedule can be changed by governance*):
* **Year 0:** 100
* **Year 1:** 113
* **Year 2:** 127
* **Year 3:** 144
* **Year 4:** 163
* **Year 5:** 184
* **Year 6:** 208
* **Year 7:** 235
* **Year 8:** 265
* **Year 9:** 300
* **Year 10:** 300
## Testnet
### How can I join the testnet?
The Testnet is a great environment to test your validator setup before launch.
We view testnet participation as a great way to signal to the community that you are ready and able to operate a validator. You can find all relevant information about the testnet [here](../join-testnet.md) and [here](https://github.com/cosmos/testnets).
### What are the different types of keys?
In short, there are two types of keys:
- **Tendermint Key**: This is a unique key used to sign consensus votes.
+ It is associated with a public key `cosmosvalconspub` (Get this value with `gaiad tendermint show-validator`)
+ It is generated when the node is created with gaiad init.
- **Application key**: This key is created from `gaiacli` and used to sign transactions. Application keys are associated with a public key prefixed by `cosmospub` and an address prefixed by `cosmos`. Both are derived from account keys generated by `gaiacli keys add`.
Note: A validator's operator key is directly tied to an application key, but
uses reserved prefixes solely for this purpose: `cosmosvaloper` and `cosmosvaloperpub`
### What are the different states a validator can be in?
After a validator is created with a `create-validator` transaction, 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 misbehavior.
- `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 Atoms 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 Atoms that must be delegated to be an active (=bonded) validator?
The minimum is `1 atom`.
### 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 Atoms:** Number of Atoms a validator self-delegated to themselves. A validator with a higher amount of self-delegated Atoms has more skin in the game, making them more liable for their actions.
* **Amount of delegated Atoms:** Total number of Atoms 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 the Cosmos Hub 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 Atoms can be thought of as a safety deposit on validation activities. When a validator or a delegator wants to retrieve part or all of their deposit, they send an `unbonding` transaction. Then, Atoms undergo a **3 weeks unbonding period** during which they are liable to being slashed for potential misbehaviors committed by the validator before the unbonding process started.
Validators, and by association delegators, receive block 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 Atoms 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' Atoms?
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' Atoms. **By no means can a validator run away with its delegator's funds**.
Even though delegated funds cannot be stolen by their validators, delegators are still liable if their validators misbehave.
### How often will a validator be chosen to propose the next block? Does it go up with the quantity of bonded Atoms?
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 Atoms) of the validator. For example, if the total bonded stake across all validators is 100 Atoms and a validator's total stake is 10 Atoms, then this validator will proposer ~10% of the blocks.
### Will validators of the Cosmos Hub ever be required to validate other zones in the Cosmos ecosystem?
Yes, they will. If governance decides so, validators of the Cosmos hub 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. Atoms on the Cosmos Hub) are inflated to produce block provisions. These provisions exist to incentivize Atom holders to bond their stake, as non-bonded Atom will be diluted over time.
* **Transaction fees:** The Cosmos Hub 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. The Cosmos Hub 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 Atoms and that each validator has 20% of self-bonded Atoms. These tokens do not go directly to the proposer. Instead, they are evenly spread among validators. So now each validator's pool has 100 Atoms. These 100 Atoms will be distributed according to each participant's stake:
* Commission: `100*80%*1% = 0.8 Atoms`
* Validator gets: `100\*20% + Commission = 20.8 Atoms`
* All delegators get: `100\*80% - Commission = 79.2 Atoms`
Then, each delegator can claim their part of the 79.2 Atoms 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 Atoms. Now comes a successful block that collects a total of 1025.51020408 Atoms in fees.
First, a 2% tax is applied. The corresponding Atoms go to the reserve pool. Reserve pool's funds can be allocated through governance to fund bounties and upgrades.
* `2% * 1025.51020408 = 20.51020408` Atoms go to the reserve pool.
1005 Atoms now remain. Let's assume that the proposer included 100% of the signatures in its block. It thus obtains the full bonus of 5%.
We have to solve this simple equation to find the reward R for each validator:
`9*R + R + R*5% = 1005 ⇔ R = 1005/10.05 = 100`
* For the proposer validator:
* The pool obtains `R + R * 5%`: 105 Atoms
* Commission: `105 * 80% * 1%` = 0.84 Atoms
* Validator's reward: `105 * 20% + Commission` = 21.84 Atoms
* Delegators' rewards: `105 * 80% - Commission` = 83.16 Atoms (each delegator will be able to claim its portion of these rewards in proportion to their stake)
* For each non-proposer validator:
* The pool obtains R: 100 Atoms
* Commission: `100 * 80% * 1%` = 0.8 Atoms
* Validator's reward: `100 * 20% + Commission` = 20.8 Atoms
* Delegators' rewards: `100 * 80% - Commission` = 79.2 Atoms (each delegator will be able to claim 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 Atoms?
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 Atoms in their staking pool. In other words, validators should have skin in the game.
In order for delegators to have some guarantee about how much skin-in-the-game their validator has, the latter can signal a minimum amount of self-delegated Atoms. 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. The Cosmos Hub 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:** Users will be warned by Cosmos Voyager if they want to delegate to a validator that already has a significant amount of staking power.
## Technical Requirements
### What are hardware requirements?
Validators should expect to provision one or more data center locations with redundant power, networking, firewalls, HSMs and servers.
We expect that a modest level of hardware specifications will be needed initially and that they might rise as network use increases. Participating in the testnet is the best way to learn more.
### What are software requirements?
In addition to running a Cosmos Hub node, validators should develop monitoring, alerting and management solutions.
### What are bandwidth requirements?
The Cosmos network has the capacity for very high throughput relative to chains like Ethereum or Bitcoin.
We recommend that the data center nodes only connect to trusted full-nodes in the cloud or other validators that know each other socially. This relieves the data center node from the burden of mitigating denial-of-service attacks.
Ultimately, as the network becomes more heavily used, multigigabyte per day bandwidth is very realistic.
### What does running a validator imply in terms of logistics?
A successful validator operation will require the efforts of multiple highly skilled individuals and continuous operational attention. This will be considerably more involved than running a bitcoin miner for instance.
### How to handle key management?
Validators should expect to run an HSM that supports ed25519 keys. Here are potential options:
* YubiHSM 2
* Ledger Nano S
* Ledger BOLOS SGX enclave
* Thales nShield support
The Tendermint team does not recommend one solution above the other. The community is encouraged to bolster the effort to improve HSMs and the security of key management.
### What can validators expect in terms of operations?
Running effective operation is the key to avoiding unexpectedly unbonding or being slashed. This includes being able to respond to attacks, outages, as well as to maintain security and isolation in your data center.
### What are the maintenance requirements?
Validators should expect to perform regular software updates to accommodate upgrades and bug fixes. There will inevitably be issues with the network early in its bootstrapping phase that will require substantial vigilance.
### How can validators protect themselves from denial-of-service attacks?
Denial-of-service attacks occur when an attacker sends a flood of internet traffic to an IP address to prevent the server at the IP address from connecting to the internet.
An attacker scans the network, tries to learn the IP address of various validator nodes and disconnect them from communication by flooding them with traffic.
One recommended way to mitigate these risks is for validators to carefully structure their network topology in a so-called sentry node architecture.
Validator nodes should only connect to full-nodes they trust because they operate them themselves or are run by other validators they know socially. A validator node will typically run in a data center. Most data centers provide direct links the networks of major cloud providers. The validator can use those links to connect to sentry nodes in the cloud. This shifts the burden of denial-of-service from the validator's node directly to its sentry nodes, and may require new sentry nodes be spun up or activated to mitigate attacks on existing ones.
Sentry nodes can be quickly spun up or change their IP addresses. Because the links to the sentry nodes are in private IP space, an internet based attacked cannot disturb them directly. This will ensure validator block proposals and votes always make it to the rest of the network.
It is expected that good operating procedures on that part of validators will completely mitigate these threats.
For more on sentry node architecture, see [this](https://forum.cosmos.network/t/sentry-node-architecture-overview/454).

222
docs/cosmos-hub/validators/validator-setup.md
View File

@ -1,222 +0,0 @@
# Run a Validator on the Cosmos Hub Mainnet
::: tip
Information on how to join the mainnet (`genesis.json` file and seeds) is held [in our `launch` repo](https://github.com/cosmos/launch/tree/master/latest).
:::
Before setting up your validator node, make sure you've already gone through the [Full Node Setup](../join-mainnet.md) guide.
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).
:::
You may want to skip the next section if you have already [set up a full-node](../join-mainnet.md).
## Create Your Validator
Your `cosmosvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
```bash
gaiad tendermint show-validator
```
To create your validator, just use the following command:
::: warning
Don't use more `uatom` than you have!
:::
```bash
gaiacli tx staking create-validator \
--amount=1000000uatom \
--pubkey=$(gaiad 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="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 stritly 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 `1atom`, or `1000000uatom`
:::
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 the Cosmos Hub 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 `cosmosvalconspub` can be used to create a new validator by staking tokens. You can find your validator pubkey by running:
```bash
gaiad tendermint show-validator
```
Next, craft your `gaiad 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 `uatom` than you have!
:::
```bash
gaiad 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 <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
gaiacli tx staking edit-validator
--moniker="choose a moniker" \
--website="https://cosmos.network" \
--identity=6A0D65E29A4CBC8E \
--details="To infinity and beyond!" \
--chain-id=<chain_id> \
--gas="auto" \
--gas-prices="0.025uatom" \
--from=<key_name> \
--commission-rate="0.10"
```
__Note__: The `commission-rate` value must adhere to the following invariants:
- Must be between 0 and the validator's `commission-max-rate`
- Must not exceed the validator's `commission-max-change-rate` which is maximum
% point change rate **per day**. In other words, a validator can only change
its commission once per day and within `commission-max-change-rate` bounds.
## View Validator Description
View the validator's information with this command:
```bash
gaiacli query 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
gaiacli query slashing signing-info <validator-pubkey>\
--chain-id=<chain_id>
```
## Unjail Validator
When a validator is "jailed" for downtime, you must submit an `Unjail` transaction from the operator account in order to be able to get block proposer rewards again (depends on the zone fee distribution).
```bash
gaiacli tx slashing unjail \
--from=<key_name> \
--chain-id=<chain_id>
```
## Confirm Your Validator is Running
Your validator is active if the following command returns anything:
```bash
gaiacli query tendermint-validator-set | grep "$(gaiad tendermint show-validator)"
```
You should now see your validator in one of the Cosmos Hub explorers. You are looking for the `bech32` encoded `address` in the `~/.gaiad/config/priv_validator.json` file.
::: warning Note
To be in the validator set, you need to have more total voting power than the 100th validator.
:::
## 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 `gaiad`.
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 `gaiad` is not running, start it up again:
```bash
gaiad 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
gaiacli status
```
You may notice that your voting power is less than it used to be. That's because you got slashed for downtime!
### Problem #2: My `gaiad` crashes because of `too many open files`
The default number of files Linux can open (per-process) is `1024`. `gaiad` is known to open more than `1024` files. This causes the process to crash. A quick fix is to run `ulimit -n 4096` (increase the number of open files allowed) and then restart the process with `gaiad start`. If you are using `systemd` or another process manager to launch `gaiad` this may require some configuration at that level. A sample `systemd` file to fix this issue is below:
```toml
# /etc/systemd/system/gaiad.service
[Unit]
Description=Cosmos Gaia Node
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/home/ubuntu/go/bin/gaiad start
Restart=on-failure
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
```

22
docs/cosmos-hub/what-is-gaia.md
View File

@ -1,22 +0,0 @@
# What is Gaia?
`gaia` is the name of the Cosmos SDK application for the Cosmos Hub. It comes with 2 main entrypoints:
- `gaiad`: The Gaia Daemon, runs a full-node of the `gaia` application.
- `gaiacli`: The Gaia command-line interface, which enables interaction with a Gaia full-node.
`gaia` is built on the Cosmos SDK using the following modules:
- `x/auth`: Accounts and signatures.
- `x/bank`: Token transfers.
- `x/staking`: Staking logic.
- `x/mint`: Inflation logic.
- `x/distribution`: Fee distribution logic.
- `x/slashing`: Slashing logic.
- `x/gov`: Governance logic.
- `x/ibc`: Inter-blockchain transfers.
- `x/params`: Handles app-level parameters.
>About the Cosmos Hub: The Cosmos Hub is the first Hub to be launched in the Cosmos Network. The role of a Hub is to facilitate transfers between blockchains. If a blockchain connects to a Hub via IBC, it automatically gains access to all the other blockchains that are connected to it. The Cosmos Hub is a public Proof-of-Stake chain. Its staking token is called the Atom.
Next, learn how to [install Gaia](./installation.md).