diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..410845f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,209 @@ +# Contributing + +* [Pull Requests](#pull-requests) + * [Process for reviewing PRs](#process-for-reviewing-prs) + * [Updating Documentation](#updating-documentation) +* [Forking](#forking) +* [Dependencies](#dependencies) +* [Testing](#testing) +* [Branching Model and Release](#branching-model-and-release) + * [PR Targeting](#pr-targeting) + * [Development Procedure](#development-procedure) + * [Pull Merge Procedure](#pull-merge-procedure) + * [Release Procedure](#release-procedure) + * [Point Release Procedure](#point-release-procedure) + +Thank you for considering making contributions to Gaia and related +repositories! + +Contributing to this repo can mean many things such as participated in +discussion or proposing code changes. To ensure a smooth workflow for all +contributors, the general procedure for contributing has been established: + + 1. either [open](https://github.com/cosmos/gaia/issues/new/choose) or + [find](https://github.com/cosmos/gaia/issues) an issue you'd like to help with, + 2. participate in thoughtful discussion on that issue, + 3. if you would then like to contribute code: + 1. if a the issue is a proposal, ensure that the proposal has been accepted, + 2. ensure that nobody else has already begun working on this issue, if they have + make sure to contact them to collaborate, + 3. if nobody has been assigned the issue and you would like to work on it + make a comment on the issue to inform the community of your intentions + to begin work, + 4. follow standard github best practices: fork the repo, branch from the + top of `master`, make some commits, and submit a PR to `master`, + - for core developers working within the Gaia repo, + to ensure a clear ownership of branches, branches must be named with the convention `yourname/{issue-}feature-name`. + 5. submit your PR early and make sure it's opened as a `Draft`, even if it's + incomplete, this indicates to the community you're working on something and + allows them to provide comments early in the development process. When the code + is complete it should be marked as ready-for-review using Github's `Mark Ready` feature. + +Note that for very small or blatantly obvious problems (such as typos) it is +not required to an open issue to submit a PR, but be aware that for more complex +problems/features, if a PR is opened before an adequate design discussion has +taken place in a github issue, that PR runs a high likelihood of being rejected. + +Take a peek at our [coding repo](https://github.com/tendermint/coding) for +overall information on repository workflow and standards. Note, we use `make +tools` for installing the linting tools. + +Other notes: + - Looking for a good place to start contributing? How about checking out some + [good first issues](https://github.com/cosmos/gaia/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) + - Please make sure to use `gofmt` before every commit - the easiest way to do + this is have your editor run it for you upon saving a file. Additionally + please ensure that your code is lint compliant by running `make lint` + +## Pull Requests + +To accommodate review process we suggest that PRs are categorically broken up. +Ideally each PR addresses only a single issue. Additionally, as much as possible +code refactoring and cleanup should be submitted as a separate PRs from bugfixes/feature-additions. + +### Process for reviewing PRs + +All PRs require two Reviews before merge (except docs changes, or variable name-changes which only require one). When reviewing PRs please use the following review explanations: + +- `LGTM` without an explicit approval means that the changes look good, but you haven't pulled down the code, run tests locally and thoroughly reviewed it. +- `Approval` through the GH UI means that you understand the code, documentation/spec is updated in the right places, you have pulled down and tested the code locally. In addition: + - You must also think through anything which ought to be included but is not + - You must think through whether any added code could be partially combined (DRYed) with existing code + - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes + - Naming must be consistent with conventions and the rest of the codebase + - Code must live in a reasonable location, considering dependency structures (e.g. not importing testing modules in production code, or including example code modules in production code). + - if you approve of the PR, you are responsible for fixing any of the issues mentioned here and more +- If you sat down with the PR submitter and did a pairing review please note that in the `Approval`, or your PR comments. +- If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. + +### Updating Documentation + +If you open a PR in Gaia, it is mandatory to update the relevant documentation in /docs. + +* If your changes relate specifically to the gaia application, please modify the docs/ folder. + +## Forking + +Please note that Go requires code to live under absolute paths, which complicates forking. +While my fork lives at `https://github.com/rigeyrigerige/gaia`, +the code should never exist at `$GOPATH/src/github.com/rigeyrigerige/gaia`. +Instead, we use `git remote` to add the fork as a new remote for the original repo, +`$GOPATH/src/github.com/cosmos/gaia `, and do all the work there. + +For instance, to create a fork and work on a branch of it, I would: + + - Create the fork on github, using the fork button. + - Go to the original repo checked out locally (i.e. `$GOPATH/src/github.com/cosmos/gaia`) + - `git remote rename origin upstream` + - `git remote add origin git@github.com:rigeyrigerige/gaia.git` + +Now `origin` refers to my fork and `upstream` refers to the Gaia version. +So I can `git push -u origin master` to update my fork, and make pull requests to Gaia from there. +Of course, replace `rigeyrigerige` with your git handle. + +To pull in updates from the origin repo, run + + - `git fetch upstream` + - `git rebase upstream/master` (or whatever branch you want) + +Please don't make Pull Requests to `master`. + +## Dependencies + +We use [Go 1.11 Modules](https://github.com/golang/go/wiki/Modules) to manage +dependency versions. + +The master branch of every Cosmos repository should just build with `go get`, +which means they should be kept up-to-date with their dependencies so we can +get away with telling people they can just `go get` our software. + +Since some dependencies are not under our control, a third party may break our +build, in which case we can fall back on `go mod tidy -v`. + +## Testing + +All repos should be hooked up to [CircleCI](https://circleci.com/). + +If they have `.go` files in the root directory, they will be automatically +tested by circle using `go test -v -race ./...`. If not, they will need a +`circle.yml`. Ideally, every repo has a `Makefile` that defines `make test` and +includes its continuous integration status using a badge in the `README.md`. + +We expect tests to use `require` or `assert` rather than `t.Skip` or `t.Fail`, +unless there is a reason to do otherwise. +When testing a function under a variety of different inputs, we prefer to use +[table driven tests](https://github.com/golang/go/wiki/TableDrivenTests). +Table driven test error messages should follow the following format +`, tc #, i #`. +`` is an optional short description of whats failing, `tc` is the +index within the table of the testcase that is failing, and `i` is when there +is a loop, exactly which iteration of the loop failed. +The idea is you should be able to see the +error message and figure out exactly what failed. +Here is an example check: + +```go + +for tcIndex, tc := range cases { + + for i := 0; i < tc.numTxsToTest; i++ { + + require.Equal(t, expectedTx[:32], calculatedTx[:32], + "First 32 bytes of the txs differed. tc #%d, i #%d", tcIndex, i) +``` + +## Branching Model and Release + +User-facing repos should adhere to the trunk based development branching model: https://trunkbaseddevelopment.com/. + +Libraries need not follow the model strictly, but would be wise to. + +Gaia utilizes [semantic versioning](https://semver.org/). + +### PR Targeting + +Ensure that you base and target your PR on the `master` branch. + +All feature additions should be targeted against `master`. Bug fixes for an outstanding release candidate +should be targeted against the release candidate branch. Release candidate branches themselves should be the +only pull requests targeted directly against master. + +### Development Procedure + - the latest state of development is on `master` + - `master` must never fail `make test` or `make test_cli` + - `master` should not fail `make lint` + - no `--force` onto `master` (except when reverting a broken commit, which should seldom happen) + - create a development branch either on github.com/cosmos/gaia, or your fork (using `git remote add origin`) + - before submitting a pull request, begin `git rebase` on top of `master` + +### Pull Merge Procedure + - ensure pull branch is rebased on `master` + - run `make test` and `make test_cli` to ensure that all tests pass + - merge pull request + +### Release Procedure + - start on `master` + - create the release candidate branch `rc/v*` (going forward known as **RC**) and ensure it's protected against pushing from anyone except the release manager/coordinator. **no PRs targeting this branch should be merged unless exceptional circumstances arise** + - on the `RC` branch, use `clog` to prepare the `CHANGELOG.md` and kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks). + - if errors are found during the simulation testing, commit the fixes to `master` and create a new `RC` branch (making sure to increment the `rcN`) + - after simulation has successfully completed, create the release branch (`release/vX.XX.X`) from the `RC` branch + - merge the release branch to `master` to incorporate the `CHANGELOG.md` updates + - delete the `RC` branches + +### Point Release Procedure + +At the moment, only a single major release will be supported, so all point +releases will be based off of that release. + + - start on `vX.XX.X` + - checkout a new branch `pre-rc/vX.X.X` + - cherry pick the desired changes from `master` + - these changes should be small and NON-BREAKING (both API and state machine) + - add entries to CHANGELOG.md and remove corresponding pending log entries + - checkout a new branch `rc/vX.X.X` based off of `vX.XX.X` + - create a PR merging `pre-rc/vX.X.X` into `rc/vX.X.X` + - run tests and simulations (noted in [Release Procedure](#release-procedure)) + - after tests and simulation have successfully completed, create the release branch `release/vX.XX.X` from the `RC` branch + - delete the `pre-rc/vX.X.X` and `RC` branches + - create a PR into `master` containing ONLY the CHANGELOG.md updates + - tag and release `release/vX.XX.X` diff --git a/README.md b/README.md index c678acc..93d1c16 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Gaia +# Cosmos Hub +[!banner](docs/welcome-banner.jpg) [![CircleCI](https://circleci.com/gh/cosmos/gaia/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/gaia/tree/master) [![codecov](https://codecov.io/gh/cosmos/gaia/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/gaia) diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md new file mode 100644 index 0000000..8c20baa --- /dev/null +++ b/docs/DOCS_README.md @@ -0,0 +1,126 @@ +# Updating the docs + +If you want to open a PR on Gaia to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/cosmos/gaia/tree/master/CONTRIBUTING.md) + +## Docs Build Workflow + +The documentation for the Cosmos SDK & Gaia is hosted at: + +- https://cosmos.network/docs/ and +- https://cosmos-staging.interblock.io/docs/ + +built from the files in this (`/docs`) directory for +[master](https://github.com/cosmos/cosmos-sdk/tree/master/docs) +and [develop](https://github.com/cosmos/cosmos-sdk/tree/develop/docs), +respectively. + +### How It Works + +There is a CircleCI job listening for changes in the `/docs` directory, on both +the `master` and `develop` branches. Any updates to files in this directory +on those branches will automatically trigger a website deployment. Under the hood, +the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo. + +## README + +The [README.md](./README.md) is also the landing page for the documentation +on the website. During the Jenkins build, the current commit is added to the bottom +of the README. + +## Config.js + +The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents +on the website docs. Note the use of relative links and the omission of +file extensions. Additional features are available to improve the look +of the sidebar. + +## Links + +**NOTE:** Strongly consider the existing links - both within this directory +and to the website docs - when moving or deleting files. + +Relative links should be used nearly everywhere, having discovered and weighed the following: + +### Relative + +Where is the other file, relative to the current one? + +- works both on GitHub and for the VuePress build +- confusing / annoying to have things like: `../../../../myfile.md` +- requires more updates when files are re-shuffled + +### Absolute + +Where is the other file, given the root of the repo? + +- works on GitHub, doesn't work for the VuePress build +- this is much nicer: `/docs/hereitis/myfile.md` +- if you move that file around, the links inside it are preserved (but not to it, of course) + +### Full + +The full GitHub URL to a file or directory. Used occasionally when it makes sense +to send users to the GitHub. + +## Building Locally + +To build and serve the documentation locally, run: + +```bash +npm install -g vuepress +``` + +then change the following line in the `config.js`: + +```js +base: "/docs/", +``` + +to: + +```js +base: "/", +``` + +Finally, go up one directory to the root of the repo and run: + +```bash +# from root of repo +vuepress build docs +cd dist/docs +python -m SimpleHTTPServer 8080 +``` + +then navigate to localhost:8080 in your browser. + +## Build RPC Docs + +First, run `make tools` from the root of repo, to install the swagger-ui tool. + +Then, edit the `swagger.yaml` manually; it is found [here](https://github.com/cosmos/gaia/blob/master/cmd/gaiacli/swagger-ui/swagger.yaml) + +Finally, run `make update_gaia_lite_docs` from the root of the repo. + +## Search + +We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs. + +## Consistency + +Because the build processes are identical (as is the information contained herein), this file should be kept in sync as +much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/develop/docs/DOCS_README.md). + +### Update and Build the RPC docs + +1. Execute the following command at the root directory to install the swagger-ui generate tool. + ```bash + make tools + ``` +2. Edit API docs + 1. Directly Edit API docs manually: `cmd/gaiacli/swagger-ui/swagger.yaml`. + 2. Edit API docs within the [Swagger Editor](https://editor.swagger.io/). Please refer to this [document](https://swagger.io/docs/specification/2-0/basic-structure/) for the correct structure in `.yaml`. +3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `cmd/gaiacli/swagger-ui`. +4. Compile gaiacli + ```bash + make install + ``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..518e145 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Cosmos Hub Documentation + +Welcome to the documentation of the **Cosmos Hub application: `gaia`**. + +## What is Gaia? + +- [Gaia](./what-is-gaia.md) + +## 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) +- [Reproducible builds](./reproducible-builds.md) + +# Contribute + +See [this file](https://github.com/cosmos/gaia/blob/master/docs/DOCS_README.md) for details of the build process and +considerations when making changes. + +# Version + + This documentation is built from the following commit: diff --git a/docs/delegator-guide-cli.md b/docs/delegator-guide-cli.md new file mode 100644 index 0000000..7db8059 --- /dev/null +++ b/docs/delegator-guide-cli.md @@ -0,0 +1,523 @@ +# 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 --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. + +- `` 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 --ledger +``` + +::: warning +**This command will only work while the Ledger is plugged in and unlocked** +::: + +- `` 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 +``` + +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 +``` +::: + +- `` 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 --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 +``` + +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 : + +// 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 + +// query all delegations made from a delegator given their address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) +gaiacli query staking delegations + +// query a specific delegation made from a delegator (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) to a validator (e.g. cosmosvaloper1n5pepvmgsfd3p2tqqgvt505jvymmstf6s9gw27) given their addresses +gaiacli query staking delegation + +// query the rewards of a delegator given a delegator address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) +gaiacli query distr rewards + +// 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 +``` + +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!!): =cosmos16m93fezfiezhvnjajzrfyszml8qm92a0w67ntjhd3d0 =1000000uatom +// Ex value for flags: =0.025uatom + +gaiacli tx send --from --gas auto --gas-adjustment 1.5 --gas-prices +``` + +### 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: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =10000000uatom, =0.025uatom + +gaiacli tx staking delegate --from --gas auto --gas-adjustment 1.5 --gas-prices + + +// 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: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =100000000uatom, =0.025uatom + +gaiacli tx staking redelegate --from --gas auto --gas-adjustment 1.5 --gas-prices + +// Withdraw all rewards +// ex value for flag: =0.025uatom + +gaiacli tx distr withdraw-all-rewards --from --gas auto --gas-adjustment 1.5 --gas-prices + + +// 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: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =10000000uatom, =0.025uatom + +gaiacli tx staking unbond --from --gas auto --gas-adjustment 1.5 --gas-prices +``` + +::: 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 + +// this returns your tx if it has been included +// use the tx hash that was displayed when you created the tx +gaiacli query tx + +``` + +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 +// =text/parameter_change/software_upgrade +// ex value for flag: =0.025uatom + +gaiacli tx gov submit-proposal --title "Test Proposal" --description "My awesome proposal" --type --deposit=10000000uatom --gas auto --gas-adjustment 1.5 --gas-prices --from + +// Increase deposit of a proposal +// Retrieve proposalID from $gaiacli query gov proposals --status deposit_period +// ex value for parameter: =10000000uatom + +gaiacli tx gov deposit --gas auto --gas-adjustment 1.5 --gas-prices --from + +// Vote on a proposal +// Retrieve proposalID from $gaiacli query gov proposals --status voting_period +//