diff --git a/README.md b/README.md index 94b2b19da848..b57cd1dff5f7 100644 --- a/README.md +++ b/README.md @@ -17,27 +17,26 @@ It is being used to build `Gaia`, the first implementation of the [Cosmos Hub](h **WARNING**: The SDK has mostly stabilized, but we are still making some breaking changes. -**Note**: Requires [Go 1.10+](https://golang.org/dl/) +**Note**: Requires [Go 1.11+](https://golang.org/dl/) ## Gaia Testnet +To install the binaries, read the [install instructions](./docs/gaia/installation.md) + To join the latest testnet, follow -[the guide](./docs/getting-started/join-testnet.md). +[the guide](./docs/gaia/join-testnet.md). For status updates and genesis files, see the [testnets repo](https://github.com/cosmos/testnets). -## Install - -See the -[install instructions](./docs/getting-started/installation.md). ## Quick Start -See the [Cosmos Docs](https://cosmos.network/docs/) +To learn how the SDK works from a high-level perspective, go to the [SDK Intro](./docs/intro/README.md). + +If you want to get started quickly and learn how to build on top of the SDK, please follow the [SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial). You can also fork the tutorial's repo to get started building your own Cosmos SDK application. -- [Getting started with the SDK](./docs/sdk/core/intro.md) -- [SDK Examples](/examples) +For more, please go to the [Cosmos SDK Docs](./docs/README.md) ## Disambiguation diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index d1c80f6d1c42..0774208ab446 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -11,6 +11,15 @@ module.exports = { lastUpdated: "Last Updated", nav: [{ text: "Back to Cosmos", link: "https://cosmos.network" }], sidebar: [ + { + title: "Overview", + collapsable: false, + children: [ + "/intro/README", + "/intro/sdk-app-architecture", + "/intro/ocap" + ] + }, { title: "Gaia", collapsable: false, @@ -21,23 +30,21 @@ module.exports = { "/gaia/validators/overview", "/gaia/validators/security", "/gaia/validators/validator-faq", - "/gaia/validators/validator-setup" + "/gaia/validators/validator-setup", + "/gaia/ledger" ] }, { title: "Clients", collapsable: false, children: [ - "/clients/clients", - "/clients/cli", - "/clients/keys", - "/clients/ledger", - "/clients/node", - "/clients/service-providers", - "/lite/", // this renders the readme - "/lite/getting_started", - "/lite/specification" - ] + "/clients/README", + "/lite/", // this renders the readme + "/lite/getting_started", + "/lite/specification", + "/clients/cli", + "/clients/service-providers" + ] } ] } diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 48a31c2ea929..a27f093b4507 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -1,4 +1,8 @@ -# Docs Build Workflow +## Updating the docs + +If you want to open a PR on the Cosmos SDK to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/master/CONTRIBUTING.md) + +## Docs Build Workflow The documentation for the Cosmos SDK is hosted at: @@ -15,34 +19,34 @@ Besides, gaia-lite API docs are also provided by gaia-lite. The default API docs https://localhost:1317/swagger-ui/ ``` -## How It Works +### How It Works There is a Jenkins 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, a private website repository has make targets consumed by a standard Jenkins task. -## README +### 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 +### 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 +### 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 +#### Relative Where is the other file, relative to the current one? @@ -50,7 +54,7 @@ Where is the other file, relative to the current one? - confusing / annoying to have things like: `../../../../myfile.md` - requires more updates when files are re-shuffled -### Absolute +#### Absolute Where is the other file, given the root of the repo? @@ -58,12 +62,12 @@ Where is the other file, given the root of the repo? - 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 +#### Full The full GitHub URL to a file or directory. Used occasionally when it makes sense to send users to the GitHub. -## Building Locally +### Building Locally To build and serve the documentation locally, run: @@ -94,12 +98,12 @@ python -m SimpleHTTPServer 8080 then navigate to localhost:8080 in your browser. -## Consistency +### 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 +### Update and Build the RPC docs 1. Execute the following command at the root directory to install the swagger-ui generate tool. ``` diff --git a/docs/README.md b/docs/README.md index e786339a6aad..fbdf89797bef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,24 +1,38 @@ -# Welcome to the Cosmos Docs! +# Welcome to the SDK Docs! + +Welcome to the SDK docs! + ![cosmonaut reading the cosmos docs in space](./cosmos-docs.jpg) -Cosmos is a decentralized network of independent parallel blockchains, each powered by classical BFT consensus algorithms like Tendermint. +## Learn the SDK + +### SDK Intro + +If you are a newcomer and would like to learn more about the Cosmos SDK, this **[intro](./intro/README.md)** is a good starting place. + +### SDK tutorial + +If you like to learn by doing, you can follow the **[SDK application tutorial](https://github.com/cosmos/sdk-application-tutorial)**. It showcases how to build an SDK-based blockchain from scratch, and teaches you about the basic principles the SDK in the process. -The first blockchain in the Cosmos Network is the Cosmos Hub, whose native token is the Atom. Cosmos is a permission-less network, meaning that anybody can build a blockchain on it. +## Use the SDK -Cosmos can interoperate with multiple other applications and cryptocurrencies. By creating a new zone, you can plug any blockchain system into the Cosmos hub and pass tokens back and forth between those zones, without the need for an intermediary. +The following sections contain the information you need if you want to build a fully-functional SDK-based blockchain: -## Quick Start +>*NOTE*: We are currently working on improving the docs. Some info might be missing. If that is the case, try the Cosmos [Forum](https://forum.cosmos.network). Failing that, [open an issue](https://github.com/cosmos/cosmos-sdk/issues/new). -- [Getting started with the SDK](./sdk/core/intro.md) -- [SDK Examples](../examples) -- [Join the testnet](./getting-started/join-testnet.md#run-a-full-node) +- [Introduction](./intro/README.md): Contains introductory high-level material on the Cosmos SDK. +- [Gaia](./gaia/README.md): Contains all documentation related to the gaia application (current name for the Cosmos-Hub). +- [Clients](./clients/README.md): Documentation about SDK clients like the SDK Command-Line interface and the SDK Light-client. +- [Specifications](./spec/README.md): Contains SDK and modules specifications. + +If you are reading this on the Cosmos Website, please know that you can find more information on [github](https://github.com/cosmos/cosmos-sdk/tree/develop/docs). Also if you find any issues with the documentation please [*open a Pull Request*](https://github.com/cosmos/cosmos-sdk/compare?expand=1), or at least [*open an Issue*](https://github.com/cosmos/cosmos-sdk/issues/new) to update the docs! + +## Join the public testnet for the Cosmos Hub + +To install the latest version of the `gaia` application and join the public testnet, **click [here](./gaia/README.md#join-the-cosmos-hub-public-testnet)** ## Edit the Documentation See [this file](./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/clients/node.md b/docs/_attic/node.md similarity index 100% rename from docs/clients/node.md rename to docs/_attic/node.md diff --git a/docs/clients/README.md b/docs/clients/README.md new file mode 100644 index 000000000000..835b6ee5095b --- /dev/null +++ b/docs/clients/README.md @@ -0,0 +1,18 @@ +# Clients + +This section explains contains information on clients for SDK based blockchain. + +>*NOTE*: This section is a WIP. + +## Light-client + +Light-clients enable users to interact with your application without having to download the entire state history but with a good level of security. + +- [Overview of light clients](./lite/README.md) +- [Starting a light-client server](./lite/getting_started.md) +- [Light-client specification](./lite/specification.md) + +## Other clients + +- [Command-Line interface for SDK-based blockchain](./cli.md) +- [Service provider doc](./service-providers.md) diff --git a/docs/clients/cli.md b/docs/clients/cli.md index dbd234d3721c..fda1ef60b91e 100644 --- a/docs/clients/cli.md +++ b/docs/clients/cli.md @@ -1,8 +1,3 @@ # CLI -See `gaiacli --help` for more details. - -Also see the [testnet -tutorial](https://github.com/cosmos/cosmos-sdk/tree/develop/cmd/gaia/testnets). - -TODO: cleanup the UX and document this properly. +> TODO: Rewrite this section to explain how CLI works for a generic SDK app. diff --git a/docs/clients/lite/getting_started.md b/docs/clients/lite/getting_started.md index b602bcc47687..15bc8a2794a5 100644 --- a/docs/clients/lite/getting_started.md +++ b/docs/clients/lite/getting_started.md @@ -13,7 +13,7 @@ To start a REST server, we need to specify the following parameters: For example:: ```bash -gaiacli rest-server --chain-id=test \ +gaiacli advanced rest-server --chain-id=test \ --laddr=tcp://localhost:1317 \ --node tcp://localhost:26657 \ --trust-node=false @@ -22,7 +22,7 @@ gaiacli rest-server --chain-id=test \ The server listens on HTTPS by default. You can set the SSL certificate to be used by the server with these additional flags: ```bash -gaiacli rest-server --chain-id=test \ +gaiacli advanced rest-server --chain-id=test \ --laddr=tcp://localhost:1317 \ --node tcp://localhost:26657 \ --trust-node=false \ diff --git a/docs/clients/rest.md b/docs/clients/rest.md deleted file mode 100644 index b48ec7d8fc98..000000000000 --- a/docs/clients/rest.md +++ /dev/null @@ -1,6 +0,0 @@ -# REST - -See `gaiacli rest-server --help` for more. - -Also see the -[work in progress API specification](https://github.com/cosmos/cosmos-sdk/pull/1314) diff --git a/docs/clients/service-providers.md b/docs/clients/service-providers.md index 11fe2c779243..b7e6d500cb01 100644 --- a/docs/clients/service-providers.md +++ b/docs/clients/service-providers.md @@ -83,7 +83,7 @@ It will display all the available commands. For each command, you can use the `- ## Setting up the Rest Server -The Rest Server acts as an intermediary between the front-end and the full-node. You don't need to run the Rest Server on the same machine as the full-node. If you intend to run the Rest Server on another machine, you need to go through the [Installation and configuration](#installation-and-configuration) again on this machine. +The Rest Server acts as an intermediary between the front-end and the full-node. You don't need to run the Rest Server on the same machine as the full-node. To start the Rest server: @@ -109,4 +109,6 @@ The Rest API documents all the available endpoints that you can use to interract The API is divided into ICS standards for each category of endpoints. For example, the [ICS20](https://cosmos.network/rpc/#/ICS20/) describes the API to interact with tokens. -To give more flexibility to implementers, we have separated the different steps that are involved in the process of sending transactions. You will be able to generate unsigned transactions (example with [coin transfer](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers)), [sign](https://cosmos.network/rpc/#/ICS20/post_tx_sign) and [broadcast](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) them with different API endpoints. This allows service providers to use their own signing mechanism for instance. +To give more flexibility to implementers, we have included the ability to generate unsigned transactions, [sign](https://cosmos.network/rpc/#/ICS20/post_tx_sign) and [broadcast](https://cosmos.network/rpc/#/ICS20/post_tx_broadcast) them with different API endpoints. This allows service providers to use their own signing mechanism for instance. + +In order to generate an unsigned transaction (example with [coin transfer](https://cosmos.network/rpc/#/ICS20/post_bank_accounts__address__transfers)), you need to use the flag `?generate_only`. diff --git a/docs/gaia/README.md b/docs/gaia/README.md new file mode 100644 index 000000000000..9ecf3da2384d --- /dev/null +++ b/docs/gaia/README.md @@ -0,0 +1,19 @@ +# Gaia Documentation + +Welcome to the `Gaia` docs. `Gaia` is the current name of the Cosmos SDK application for the Cosmos Hub. + +## Join the Cosmos Hub public testnet + +- [Install the `gaia` application](./installation.md) +- [Join the current testnet](./join-testnet.md) +- [Upgrade to a validator node](./validators/validator-setup.md) + +## Setup your own `gaia` testnet + +- [Setup your own `gaia` testnet](./networks.md) + +## Additional resources + +- [Intro to validators](./validators/overview.md) +- [Validator FAQ](./validators/validator-faq.md) +- [Validator security considerations](./validators/security.md) diff --git a/docs/clients/clients.md b/docs/gaia/gaiacli.md similarity index 93% rename from docs/clients/clients.md rename to docs/gaia/gaiacli.md index ee0157ed8217..44b26d7c296c 100644 --- a/docs/clients/clients.md +++ b/docs/gaia/gaiacli.md @@ -1,4 +1,4 @@ -# Clients +# Gaia client ## Gaia CLI @@ -200,13 +200,13 @@ On the upcoming mainnet, you can delegate `atom` to a validator. These [delegato You can query the list of all validators of a specific chain: ```bash -gaiacli query validators +gaiacli query stake validators ``` If you want to get the information of a single validator you can check it with: ```bash -gaiacli query validator +gaiacli query stake validator ``` #### Bond Tokens @@ -214,7 +214,7 @@ gaiacli query validator On the testnet, we delegate `steak` instead of `atom`. Here's how you can bond tokens to a testnet validator (*i.e.* delegate): ```bash -gaiacli tx delegate \ +gaiacli tx stake delegate \ --amount=10steak \ --validator= \ --from= \ @@ -240,7 +240,7 @@ Don't use more `steak` thank you have! You can always get more by using the [Fau Once submitted a delegation to a validator, you can see it's information by using the following command: ```bash -gaiacli query delegation \ +gaiacli query stake delegation \ --address-delegator= \ --validator= ``` @@ -248,7 +248,7 @@ gaiacli query delegation \ Or if you want to check all your current delegations with disctinct validators: ```bash -gaiacli query delegations +gaiacli query stake delegations ``` You can also get previous delegation(s) status by adding the `--height` flag. @@ -258,7 +258,7 @@ You can also get previous delegation(s) status by adding the `--height` flag. If for any reason the validator misbehaves, or you just want to unbond a certain amount of tokens, use this following command. You can unbond a specific `shares-amount` (eg:`12.1`\) or a `shares-fraction` (eg:`0.25`) with the corresponding flags. ```bash -gaiacli tx unbond begin \ +gaiacli tx stake unbond \ --validator= \ --shares-fraction=0.5 \ --from= \ @@ -272,7 +272,7 @@ The unbonding will be automatically completed when the unbonding period has pass Once you begin an unbonding-delegation, you can see it's information by using the following command: ```bash -gaiacli query unbonding-delegation \ +gaiacli query stake unbonding-delegation \ --address-delegator= \ --validator= \ ``` @@ -280,13 +280,13 @@ gaiacli query unbonding-delegation \ Or if you want to check all your current unbonding-delegations with disctinct validators: ```bash -gaiacli query unbonding-delegations +gaiacli query stake unbonding-delegations ``` Additionally, as you can get all the unbonding-delegations from a particular validator: ```bash - gaiacli query unbonding-delegations-from + gaiacli query stake unbonding-delegations-from ``` To get previous unbonding-delegation(s) status on past blocks, try adding the `--height` flag. @@ -296,7 +296,7 @@ To get previous unbonding-delegation(s) status on past blocks, try adding the `- A redelegation is a type delegation that allows you to bond illiquid tokens from one validator to another: ```bash -gaiacli tx redelegate begin \ +gaiacli tx stake redelegate \ --addr-validator-source= \ --addr-validator-dest= \ --shares-fraction=50 \ @@ -313,7 +313,7 @@ The redelegation will be automatically completed when the unbonding period has p Once you begin an redelegation, you can see it's information by using the following command: ```bash -gaiacli query redelegation \ +gaiacli query stake redelegation \ --address-delegator= \ --addr-validator-source= \ --addr-validator-dest= \ @@ -322,13 +322,13 @@ gaiacli query redelegation \ Or if you want to check all your current unbonding-delegations with disctinct validators: ```bash -gaiacli query redelegations +gaiacli query stake redelegations ``` Additionally, as you can get all the outgoing redelegations from a particular validator: ```bash - gaiacli query redelegations-from + gaiacli query stake redelegations-from ``` To get previous redelegation(s) status on past blocks, try adding the `--height` flag. @@ -337,8 +337,8 @@ To get previous redelegation(s) status on past blocks, try adding the `--height` Parameters define high level settings for staking. You can get the current values by using: -``` -gaiacli query parameters +```bash +gaiacli query stake parameters ``` With the above command you will get the values for: @@ -353,8 +353,8 @@ All these values will be subject to updates though a `governance` process by `Pa A staking `Pool` defines the dynamic parameters of the current state. You can query them with the following command: -``` -gaiacli query pool +```bash +gaiacli query stake pool ``` With the `pool` command you will get the values for: @@ -388,7 +388,7 @@ In order to create a governance proposal, you must submit an initial deposit alo - `type`: Type of proposal. Must be of value _Text_ (types _SoftwareUpgrade_ and _ParameterChange_ not supported yet). ```bash -gaiacli tx submit-proposal \ +gaiacli tx gov submit-proposal \ --title= \ --description=<description> \ --type=<Text/ParameterChange/SoftwareUpgrade> \ @@ -402,13 +402,13 @@ gaiacli tx submit-proposal \ Once created, you can now query information of the proposal: ```bash -gaiacli query proposal --proposal-id=<proposal_id> +gaiacli query gov proposal --proposal-id=<proposal_id> ``` Or query all available proposals: ```bash -gaiacli query proposals +gaiacli query gov proposals ``` You can also query proposals filtered by `voter` or `depositer` by using the corresponding flags. @@ -418,7 +418,7 @@ You can also query proposals filtered by `voter` or `depositer` by using the cor In order for a proposal to be broadcasted to the network, the amount deposited must be above a `minDeposit` value (default: `10 steak`). If the proposal you previously created didn't meet this requirement, you can still increase the total amount deposited to activate it. Once the minimum deposit is reached, the proposal enters voting period: ```bash -gaiacli tx deposit \ +gaiacli tx gov deposit \ --proposal-id=<proposal_id> \ --deposit=<200steak> \ --from=<name> \ @@ -432,13 +432,13 @@ gaiacli tx deposit \ Once a new proposal is created, you can query all the deposits submitted to it: ```bash -gaiacli query deposits --proposal-id=<proposal_id> +gaiacli query gov deposits --proposal-id=<proposal_id> ``` You can also query a deposit submitted by a specific address: ```bash -gaiacli query deposit \ +gaiacli query gov deposit \ --proposal-id=<proposal_id> \ --depositer=<account_cosmos> ``` @@ -448,7 +448,7 @@ gaiacli query deposit \ 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 vote \ +gaiacli tx gov vote \ --proposal-id=<proposal_id> \ --option=<Yes/No/NoWithVeto/Abstain> \ --from=<name> \ @@ -460,7 +460,7 @@ gaiacli tx vote \ Check the vote with the option you just submitted: ```bash -gaiacli query vote \ +gaiacli query gov vote \ --proposal-id=<proposal_id> \ --voter=<account_cosmos> ``` @@ -468,7 +468,7 @@ gaiacli query vote \ You can also get all the previous votes submitted to the proposal with: ```bash -gaiacli query votes --proposal-id=<proposal_id> +gaiacli query gov votes --proposal-id=<proposal_id> ``` #### Query proposal tally results @@ -476,5 +476,5 @@ gaiacli query votes --proposal-id=<proposal_id> To check the current tally of a given proposal you can use the `tally` command: ```bash -gaiacli query tally --proposal-id=<proposal_id> +gaiacli query gov tally --proposal-id=<proposal_id> ``` diff --git a/docs/gaia/installation.md b/docs/gaia/installation.md index 66ccae4b85e8..c4b78b13cbc9 100644 --- a/docs/gaia/installation.md +++ b/docs/gaia/installation.md @@ -1,6 +1,6 @@ -# Install the SDK +# Install Gaia -This guide will explain how to install the [Cosmos SDK](/sdk/overview.md) onto your system. With the SDK installed on a server, you can participate in the latest testnet as either a [Full Node](./join-testnet.md#run-a-full-node) or a [Validator](/validators/validator-setup.md). +This guide will explain how to install the `gaiad` and `gaiacli` entrypoints onto your system. With these installed on a server, you can participate in the latest testnet as either a [Full Node](./join-testnet.md#run-a-full-node) or a [Validator](./validators/validator-setup.md). ## Install Go @@ -14,17 +14,13 @@ echo "export PATH=$PATH:$GOBIN" >> ~/.bash_profile ``` ::: tip -**Go 1.10+** is required for the Cosmos SDK. +**Go 1.11+** is required for the Cosmos SDK. ::: ## Install Cosmos SDK -Next, let's install the testnet's version of the Cosmos SDK. -You can find information about the latest testnet and the right -version of the Cosmos-SDK for it in the [testnets -repo](https://github.com/cosmos/testnets#testnet-status). -Here we'll use the `master` branch, which contains the latest stable release. -If necessary, make sure you `git checkout` the correct +Next, let's install the latest version of Gaia. Here we'll use the `master` branch, which contains the latest stable release. +If necessary, make sure you `git checkout` the correct [released version](https://github.com/cosmos/cosmos-sdk/releases). ```bash @@ -35,6 +31,8 @@ cd cosmos-sdk && git checkout master make get_tools && make get_vendor_deps && make install ``` +> *NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed. + That will install the `gaiad` and `gaiacli` binaries. Verify that everything is OK: ```bash @@ -44,4 +42,4 @@ $ gaiacli version ## Run a Full Node -With Cosmos SDK installed, you can run [a full node on the latest testnet](full-node.md). +With the binaries installed, you can run [a full node on the latest testnet](./join-testnet.md). diff --git a/docs/gaia/join-testnet.md b/docs/gaia/join-testnet.md index ce070c4fe967..7bc058123fc6 100644 --- a/docs/gaia/join-testnet.md +++ b/docs/gaia/join-testnet.md @@ -1,21 +1,23 @@ # Join the Testnet ::: tip Current Testnet -See the [testnet repo](https://github.com/cosmos/testnets) for +See the [testnet repo](https://github.com/cosmos/testnets) for information on the latest testnet, including the correct version of the Cosmos-SDK to use and details about the genesis file. ::: -Please ensure you have the [Cosmos SDK](/getting-started/installation.md) installed. If you ran a full node on a previous testnet, please skip to [Upgrading From Previous Testnet](#upgrading-from-previous-testnet). +**Please ensure you have the [gaia binaries](.//installation.md) installed.** + +If you ran a full node on a previous testnet, please skip to [Upgrading From Previous Testnet](#upgrading-from-previous-testnet). ## Setting Up a New Node -These instructions are for setting up a brand new full node from scratch. +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 --skip-genesis --name <your_custom_name> +gaiad init ``` ::: warning Note @@ -75,10 +77,12 @@ git fetch --all && git checkout master make update_tools && make get_vendor_deps && make install ``` +> *NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed. + 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) +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! @@ -94,20 +98,16 @@ mkdir -p $HOME/.gaiad/config curl https://raw.githubusercontent.com/cosmos/testnets/master/latest/genesis.json > $HOME/.gaiad/config/genesis.json ``` -Note we use the `latest` directory in the [testnets repo](https://github.com/cosmos/testnets) -which contains details for the latest testnet. If you are connecting to a different testnet, ensure you -get the right files. +Note we use the `latest` directory in the [testnets repo](https://github.com/cosmos/testnets) +which contains details for the latest testnet. If you are connecting to a different testnet, ensure you get the right files. ### Add Seed Nodes -Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.gaiad/config/config.toml`. Here are some seed nodes you can use: +Your node needs to know how to find peers. You'll need to add healthy seed nodes to `$HOME/.gaiad/config/config.toml`. The `testnets` repo contains links to the seed nodes for each testnet. If you are looking to join the running testnet please [check the repository for details](https://github.com/cosmos/testnets) on which nodes to use. -```toml -# Comma separated list of seed nodes to connect to -seeds = "718145d422a823fd2a4e1e36e91b92bb0c4ddf8e@gaia-testnet.coinculture.net:26656,5922bf29b48a18c2300b85cc53f424fce23927ab@67.207.73.206:26656,7c8b8fd03577cd4817f5be1f03d506f879df98d8@gaia-7000-seed1.interblock.io:26656,a28737ff02391a6e00a1d3b79befd57e68e8264c@gaia-7000-seed2.interblock.io:26656,987ffd26640cd03d08ed7e53b24dfaa7956e612d@gaia-7000-seed3.interblock.io:26656" -``` +If those seeds aren't working, you can find more seeds and persistent peers on the [Cosmos Explorer](https://explorer.cosmos.network/nodes). Open the the `Full Nodes` pane and select nodes that do not have private (`10.x.x.x`) or [local IP addresses](https://en.wikipedia.org/wiki/Private_network). The `Persistent Peer` field contains the connection string. For best results use 4-6. -If those seeds aren't working, you can find more seeds and persistent peers on the [Cosmos Explorer](https://explorecosmos.network/nodes). Open the the `Full Nodes` pane and select nodes that do not have private (`10.x.x.x`) or [local IP addresses](https://en.wikipedia.org/wiki/Private_network). The `Persistent Peer` field contains the connection string. For best results use 4-6. +You can also ask for peers on the [Validators Riot Room](https://riot.im/app/#/room/#cosmos-validators:matrix.org) For more information on seeds and peers, you can [read this](https://github.com/tendermint/tendermint/blob/develop/docs/using-tendermint.md#peers). @@ -130,4 +130,4 @@ View the status of the network with the [Cosmos Explorer](https://explorecosmos. ## 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). +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). diff --git a/docs/clients/keys.md b/docs/gaia/keys.md similarity index 100% rename from docs/clients/keys.md rename to docs/gaia/keys.md diff --git a/docs/clients/ledger.md b/docs/gaia/ledger.md similarity index 100% rename from docs/clients/ledger.md rename to docs/gaia/ledger.md diff --git a/docs/gaia/validators/validator-setup.md b/docs/gaia/validators/validator-setup.md index d07697136fbd..ce63155901b5 100644 --- a/docs/gaia/validators/validator-setup.md +++ b/docs/gaia/validators/validator-setup.md @@ -1,14 +1,14 @@ # Validator Setup -::: warning Current Testnet -The current testnet is `gaia-8000`. +::: +Information on how to join the current testnet (`genesis.json` file and seeds) is held [in our `testnet` repo](https://github.com/cosmos/testnets/tree/master/latest). Please check there if you are looking to join our latest testnet. ::: Before setting up your validator node, make sure you've already gone through the [Full Node Setup](/docs/getting-started/full-node.md) guide. ## Running a Validator Node -[Validators](/validators/overview.md) are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable, double sign a transaction, or don't cast their votes. Please read about [Sentry Node Architecture](/validators/validator-faq.md#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS attacks and to ensure high-availability. +[Validators](/validators/overview.md) are responsible for committing new blocks to the blockchain through voting. A validator's stake is slashed if they become unavailable or sign blocks at the same height. Please read about [Sentry Node Architecture](/validators/validator-faq.md#how-can-validators-protect-themselves-from-denial-of-service-attacks) to protect your node from DDOS attacks and to ensure high-availability. ::: danger Warning If you want to become a validator for the Hub's `mainnet`, you should [research security](/validators/security.md). @@ -22,14 +22,14 @@ Your `cosmosvalconspub` can be used to create a new validator by staking tokens. gaiad tendermint show-validator ``` -Next, craft your `gaiacli tx create-validator` command: +Next, craft your `gaiacli tx stake create-validator` command: ::: warning Note Don't use more `steak` thank you have! You can always get more by using the [Faucet](https://faucetcosmos.network/)! ::: ```bash -gaiacli tx create-validator \ +gaiacli tx stake create-validator \ --amount=5steak \ --pubkey=$(gaiad tendermint show-validator) \ --moniker="choose a moniker" \ @@ -44,6 +44,10 @@ __Note__: When specifying commission parameters, the `commission-max-change-rate is used to measure % _point_ change over the `commission-rate`. E.g. 1% to 2% is a 100% rate increase, but only 1 percentage point. +::: tip +Use `gaiacli tx stake create-validator -h` to get a list of all the available flags. +::: + ### Edit Validator Description You can edit your validator's public description. This info is to identify your validator, and will be relied on by delegators to decide which validators to stake to. Make sure to provide input for every flag below, otherwise the field will default to empty (`--moniker` defaults to the machine name). @@ -51,7 +55,7 @@ You can edit your validator's public description. This info is to identify your 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 edit-validator +gaiacli tx stake edit-validator --moniker="choose a moniker" \ --website="https://cosmos.network" \ --identity=6A0D65E29A4CBC8E \ @@ -73,7 +77,7 @@ __Note__: The `commission-rate` value must adhere to the following invariants: View the validator's information with this command: ```bash -gaiacli query validator <account_cosmos> +gaiacli query stake validator <account_cosmos> ``` ### Track Validator Signing Information @@ -81,7 +85,7 @@ gaiacli query validator <account_cosmos> 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 signing-info <validator-pubkey>\ +gaiacli query slashing signing-info <validator-pubkey>\ --chain-id=<chain_id> ``` @@ -90,7 +94,7 @@ gaiacli query signing-info <validator-pubkey>\ 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 unjail \ +gaiacli tx slashing unjail \ --from=<key_name> \ --chain-id=<chain_id> ``` @@ -124,7 +128,7 @@ gaiad start Wait for your full node to catch up to the latest block. Next, run the following command. Note that `<cosmos>` is the address of your validator account, and `<name>` is the name of the validator account. You can find this info by running `gaiacli keys list`. ```bash -gaiacli tx unjail <cosmos> --chain-id=<chain_id> --from=<from> +gaiacli tx slashing unjail <cosmos> --chain-id=<chain_id> --from=<from> ``` ::: danger Warning diff --git a/docs/intro/README.md b/docs/intro/README.md new file mode 100644 index 000000000000..83dcc31c56ee --- /dev/null +++ b/docs/intro/README.md @@ -0,0 +1,43 @@ +# SDK Intro + +The [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk) is a framework for building multi-asset Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as Proof-Of-Authority (PoA) blockchains. + +The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the SDK as the npm-like framework to build secure blockchain applications on top of [Tendermint](https://github.com/tendermint/tendermint). + +It is based on two major principles: + +- **Composability:** Anyone can create a module for the Cosmos-SDK, and integrating the already-built modules is as simple as importing them into your blockchain application. + +- **Capabilities:** The SDK is inspired by capabilities-based security, and informed by years of wrestling with blockchain state-machines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos-SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on object-cababilities. In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called keepers that can be passed to other modules to grant a pre-defined set of capabilities. For example, if an instance of module A's keepers is passed to module B, the latter will be able to call a restricted set of module A's functions. The capabilities of each keeper are defined by the module's developer, and it's the developer's job to understand and audit the safety of foreign code from 3rd party modules based on the capabilities they are passing into each third party module. For a deeper look at capabilities, jump to [this section](./capabilities.md). + +## Learn more about the SDK + +- [SDK application architecture](./design.md) +- [SDK security paradigm: ocap](./ocap.md) + +## Creating a new SDK project + +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. +- Copy the `docs/examples/basecoin` directory. +- Use community tools! More info to come. + +## SDK Directory Structure + +The SDK is laid out in the following directories: + +- `baseapp`: Defines the template for a basic [ABCI](https://github.com/tendermint/tendermint/tree/master/abci) application so that your Cosmos-SDK application can communicate with the underlying Tendermint node. +- `client`: CLI and REST server tooling for interacting with SDK application. +- `examples`: Examples of how to build working standalone applications. +- `server`: The full node server for running an SDK application on top of + Tendermint. +- `store`: The database of the SDK - a Merkle multistore supporting multiple types of underling Merkle key-value stores. +- `types`: Common types in SDK applications. +- `x`: Extensions to the core, where all messages and handlers are defined. + +## Languages + +The Cosmos-SDK is currently written in [Golang](https://golang.org/), though the +framework could be implemented similarly in other languages. +Contact us for information about funding an implementation in another language. diff --git a/docs/intro/ocap.md b/docs/intro/ocap.md new file mode 100644 index 000000000000..7e0c9e799b37 --- /dev/null +++ b/docs/intro/ocap.md @@ -0,0 +1,102 @@ +# Object-Capability Model + +## Intro + +When thinking about security, it is good to start with a specific threat +model. Our threat model is the following: + +> We assume that a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules. + +The Cosmos SDK is designed to address this threat by being the +foundation of an object capability system. + +> The structural properties of object capability systems favor +> modularity in code design and ensure reliable encapsulation in +> code implementation. +> +> These structural properties facilitate the analysis of some +> security properties of an object-capability program or operating +> system. Some of these — in particular, information flow properties +> — can be analyzed at the level of object references and +> connectivity, independent of any knowledge or analysis of the code +> that determines the behavior of the objects. +> +> As a consequence, these security properties can be established +> and maintained in the presence of new objects that contain unknown +> and possibly malicious code. +> +> These structural properties stem from the two rules governing +> access to existing objects: +> +> 1. An object A can send a message to B only if object A holds a +> reference to B. +> 2. An object A can obtain a reference to C only +> if object A receives a message containing a reference to C. As a +> consequence of these two rules, an object can obtain a reference +> to another object only through a preexisting chain of references. +> In short, "Only connectivity begets connectivity." + +For an introduction to object-capabilities, see [this article](http://habitatchronicles.com/2017/05/what-are-capabilities/). + +Strictly speaking, Golang does not implement object capabilities +completely, because of several issues: + +- pervasive ability to import primitive modules (e.g. "unsafe", "os") +- pervasive ability to [override module vars](https://github.com/golang/go/issues/23161) +- data-race vulnerability where 2+ goroutines can create illegal interface values + +The first is easy to catch by auditing imports and using a proper +dependency version control system like Dep. The second and third are +unfortunate but it can be audited with some cost. + +Perhaps [Go2 will implement the object capability +model](https://github.com/golang/go/issues/23157). + +## Ocaps in practice + +The idea is to only reveal what is necessary to get the work done. + +For example, the following code snippet violates the object capabilities +principle: + +```go +type AppAccount struct {...} +var account := &AppAccount{ + Address: pub.Address(), + Coins: sdk.Coins{{"ATM", 100}}, +} +var sumValue := externalModule.ComputeSumValue(account) +``` + +The method `ComputeSumValue` implies a pure function, yet the implied +capability of accepting a pointer value is the capability to modify that +value. The preferred method signature should take a copy instead. + +```go +var sumValue := externalModule.ComputeSumValue(*account) +``` + +In the Cosmos SDK, you can see the application of this principle in the +[basecoin examples folder](../examples/basecoin). + +```go +// File: cosmos-sdk/examples/basecoin/app/init_handlers.go +package app + +import ( + "github.com/cosmos/cosmos-sdk/x/bank" + "github.com/cosmos/cosmos-sdk/x/sketchy" +) + +func (app *BasecoinApp) initRouterHandlers() { + + // All handlers must be added here. + // The order matters. + app.router.AddRoute("bank", bank.NewHandler(app.accountKeeper)) + app.router.AddRoute("sketchy", sketchy.NewHandler()) +} +``` + +In the Basecoin example, the sketchy handler isn't provided an account +mapper, which does provide the bank handler with the capability (in +conjunction with the context of a transaction run). \ No newline at end of file diff --git a/docs/intro/sdk-app-architecture.md b/docs/intro/sdk-app-architecture.md new file mode 100644 index 000000000000..4b302bd33439 --- /dev/null +++ b/docs/intro/sdk-app-architecture.md @@ -0,0 +1,62 @@ +# SDK Application Architecture + +## Parts of a SDK blockchain + +A blockchain application is just a [replicated deterministic state machine](https://en.wikipedia.org/wiki/State_machine_replication). As a developer, you just have to define the state machine (i.e. what the state, a starting state and messages that trigger state transitions), and [*Tendermint*](https://tendermint.com/docs/introduction/introduction.html) will handle replication over the network for you. + +>Tendermint is an application-agnostic engine that is responsible for handling the *networking* and *consensus* layers of your blockchain. In practice, this means that Tendermint is reponsible for propagating and ordering transaction bytes. Tendermint Core relies on an eponymous Byzantine-Fault-Tolerant (BFT) algorithm to reach consensus on the order of transactions. For more on Tendermint, click [here](https://tendermint.com/docs/introduction/introduction.html). + +Tendermint passes transactions from the network to the application through an interface called the [ABCI](https://github.com/tendermint/tendermint/tree/master/abci. If you look at the architecture of the blockchain node you are building, it looks like the following: + +``` ++---------------------+ +| | +| Application | +| | ++--------+---+--------+ + ^ | + | | ABCI + | v ++--------+---+--------+ +| | +| | +| Tendermint | +| | +| | ++---------------------+ +``` + +Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](#baseapp). + +## BaseApp + +Implements an ABCI App using a [MultiStore](../reference/store) for persistence and a Router to handle transactions. +The goal is to provide a secure interface between the store and the extensible state machine while defining as little about that state machine as possible (staying true to the ABCI). + +For more on `baseapp`, please go to the [baseapp reference](../reference/baseapp.md). + +## Modules + +The power of the SDK lies in its modularity. SDK blockchains are built out of customizable and interoperable modules. These modules are contained in the `x/` folder. + +In addition to the already existing modules in `x/`, that anyone can use in their app, the SDK lets you build your own custom modules. In other words, building a SDK blockchain consists in importing some modules and building others (the ones you need that do not exist yet!). + +Some core modules include: + +- `x/auth`: Used to manage accounts and signatures. +- `x/bank`: Used to enable tokens and token transfers. +- `x/staking` + `x/slashing`: Used to build Proof-Of-Stake blockchains. + +## Basecoin + +Basecoin is the first complete application in the stack. Complete applications require extensions to the core modules of the SDK to actually implement handler functionality. + +Basecoin implements a `BaseApp` state machine using the `x/auth` and `x/bank` modules, which define how transaction signers are authenticated and how coins are transferred. It should also use `x/ibc` and probably a simple staking extension. + +Basecoin and the native `x/` extensions use go-amino for all serialization needs, including for transactions and accounts. + +## SDK tutorial + +If you want to learn more about how to build an SDK application and get a deepeer understanding of the concepts presented above in the process, please check out the [SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial). + + diff --git a/docs/reference/baseapp.md b/docs/reference/baseapp.md new file mode 100644 index 000000000000..3eaf1e2f7bf4 --- /dev/null +++ b/docs/reference/baseapp.md @@ -0,0 +1,14 @@ +# baseApp + +`baseApp` requires stores to be mounted via capabilities keys - handlers can only access stores they're given the key to. The `baseApp` ensures all stores are properly loaded, cached, and committed. One mounted store is considered the "main" - it holds the latest block header, from which we can find and load the most recent state. + +`baseApp` distinguishes between two handler types - the `AnteHandler` and the `MsgHandler`. The former is a global validity check (checking nonces, sigs and sufficient balances to pay fees, +e.g. things that apply to all transaction from all modules), the later is the full state transition function. +During CheckTx the state transition function is only applied to the checkTxState and should return +before any expensive state transitions are run (this is up to each developer). It also needs to return the estimated +gas cost. + +During DeliverTx the state transition function is applied to the blockchain state and the transactions +need to be fully executed. + +BaseApp is responsible for managing the context passed into handlers - it makes the block header available and provides the right stores for CheckTx and DeliverTx. BaseApp is completely agnostic to serialization formats. \ No newline at end of file diff --git a/docs/sdk.md b/docs/sdk.md deleted file mode 100644 index 08885e875ba1..000000000000 --- a/docs/sdk.md +++ /dev/null @@ -1,244 +0,0 @@ -# Cosmos SDK Overview - -The [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk) is a framework for building multi-asset Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as Proof-Of-Authority (PoA) blockchains. - -The goal of the Cosmos-SDK is to allow developers to easily create custom interoperable blockchain applications within the Cosmos Network without having to recreate common blockchain functionality, thus removing the complexity of building a Tendermint ABCI application. We envision the SDK as the npm-like framework to build secure blockchain applications on top of Tendermint. - -In terms of its design, the SDK optimizes flexibility and security. The framework is designed around a modular execution stack which allows applications to mix and match elements as desired. In addition, all modules are sandboxed for greater application security. - -It is based on two major principles: - -- **Composability:** Anyone can create a module for the Cosmos-SDK and integrating the already-built modules is as simple as importing them into your blockchain application. - -- **Capabilities:** The SDK is inspired by capabilities-based security, and informed by years of wrestling with blockchain state-machines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos-SDK is an open framework and that we assume that some of those modules may be malicious, we designed the SDK using object-capabilities (ocaps) based principles. In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called keepers that can be passed to other modules to grant a pre-defined set of capabilities. For example, if an instance of module A's keepers is passed to module B, the latter will be able to call a restricted set of module A's functions. The capabilities of each keeper are defined by the module's developer, and it's the developer's job to understand and audit the safety of foreign code from 3rd party modules based on the capabilities they are passing into each 3rd party module. For a deeper look at capabilities, you can read this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). - -For an introduction to object-capabilities, see this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). - -## Languages - -The Cosmos-SDK is currently written in [Golang](https://golang.org/), though the -framework could be implemented similarly in other languages. -Contact us for information about funding an implementation in another language. - -## Directory Structure - -The SDK is laid out in the following directories: - -- `baseapp`: Defines the template for a basic [ABCI](https://cosmos.network/whitepaper#abci) application so that your Cosmos-SDK application can communicate with the underlying Tendermint node. -- `client`: CLI and REST server tooling for interacting with SDK application. -- `examples`: Examples of how to build working standalone applications. -- `server`: The full node server for running an SDK application on top of - Tendermint. -- `store`: The database of the SDK - a Merkle multistore supporting multiple types of underling Merkle key-value stores. -- `types`: Common types in SDK applications. -- `x`: Extensions to the core, where all messages and handlers are defined. - -## Object-Capability Model - -When thinking about security, it's good to start with a specific threat -model. Our threat model is the following: - -> We assume that a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules. - -The Cosmos-SDK is designed to address this threat by being the -foundation of an object capability system. - -> The structural properties of object capability systems favor -> modularity in code design and ensure reliable encapsulation in -> code implementation. -> -> These structural properties facilitate the analysis of some -> security properties of an object-capability program or operating -> system. Some of these — in particular, information flow properties -> — can be analyzed at the level of object references and -> connectivity, independent of any knowledge or analysis of the code -> that determines the behavior of the objects. -> -> As a consequence, these security properties can be established -> and maintained in the presence of new objects that contain unknown -> and possibly malicious code. -> -> These structural properties stem from the two rules governing -> access to existing objects: -> -> 1. An object A can send a message to B only if object A holds a -> reference to B. -> 2. An object A can obtain a reference to C only -> if object A receives a message containing a reference to C. As a -> consequence of these two rules, an object can obtain a reference -> to another object only through a preexisting chain of references. -> In short, "Only connectivity begets connectivity." - -See the [wikipedia -article](https://en.wikipedia.org/wiki/Object-capability_model) on the Object Capability Model for more -information. - -Strictly speaking, Golang does not implement object capabilities -completely, because of several issues: - -- pervasive ability to import primitive modules (e.g. "unsafe", "os") -- pervasive ability to override module vars <https://github.com/golang/go/issues/23161> -- data-race vulnerability where 2+ goroutines can create illegal interface values - -The first is easy to catch by auditing imports and using a proper -dependency version control system like Dep. The second and third are -unfortunate but it can be audited with some cost. - -Perhaps [Go2 will implement the object capability -model](https://github.com/golang/go/issues/23157). - -### What does it look like? - -Only reveal what is necessary to get the work done. - -For example, the following code snippet violates the object capabilities -principle: - -```go -type AppAccount struct {...} -var account := &AppAccount{ - Address: pub.Address(), - Coins: sdk.Coins{{"ATM", 100}}, -} -var sumValue := externalModule.ComputeSumValue(account) -``` - -The method `ComputeSumValue` implies a pure function, yet the implied -capability of accepting a pointer value is the capability to modify that -value. The preferred method signature should take a copy instead. - -```go -var sumValue := externalModule.ComputeSumValue(*account) -``` - -In the Cosmos SDK, you can see the application of this principle in the -basecoin examples folder. - -```go -// File: cosmos-sdk/examples/basecoin/app/init_handlers.go -package app - -import ( - "github.com/cosmos/cosmos-sdk/x/bank" - "github.com/cosmos/cosmos-sdk/x/sketchy" -) - -func (app *BasecoinApp) initRouterHandlers() { - - // All handlers must be added here. - // The order matters. - app.router.AddRoute("bank", bank.NewHandler(app.accountKeeper)) - app.router.AddRoute("sketchy", sketchy.NewHandler()) -} -``` - -In the Basecoin example, the sketchy handler isn't provided an account -mapper, which does provide the bank handler with the capability (in -conjunction with the context of a transaction run). - -## Application Architecture - -The SDK has multiple levels of "application": the ABCI app, the BaseApp, the BasecoinApp, and now your App. - -### ABCI App - -The basic ABCI interface allowing Tendermint to drive the applications state machine with transaction blocks. - -### BaseApp - -Implements an ABCI App using a MultiStore for persistence and a Router to handle transactions. -The goal is to provide a secure interface between the store and the extensible state machine -while defining as little about that state machine as possible (staying true to the ABCI). - -BaseApp requires stores to be mounted via capabilities keys - handlers can only access -stores they're given the key for. The BaseApp ensures all stores are properly loaded, cached, and committed. -One mounted store is considered the "main" - it holds the latest block header, from which we can find and load the most recent state. - -BaseApp distinguishes between two handler types - the `AnteHandler` and the `MsgHandler`. -The former is a global validity check (checking nonces, sigs and sufficient balances to pay fees, -e.g. things that apply to all transaction from all modules), the later is the full state transition function. -During CheckTx the state transition function is only applied to the checkTxState and should return -before any expensive state transitions are run (this is up to each developer). It also needs to return the estimated -gas cost. - -During DeliverTx the state transition function is applied to the blockchain state and the transactions -need to be fully executed. - -BaseApp is responsible for managing the context passed into handlers - it makes the block header available and provides the right stores for CheckTx and DeliverTx. BaseApp is completely agnostic to serialization formats. - -### Basecoin - -Basecoin is the first complete application in the stack. Complete applications require extensions to the core modules of the SDK to actually implement handler functionality. - -The native extensions of the SDK, useful for building Cosmos Zones, live under `x`. -Basecoin implements a `BaseApp` state machine using the `x/auth` and `x/bank` extensions, -which define how transaction signers are authenticated and how coins are transferred. -It should also use `x/ibc` and probably a simple staking extension. - -Basecoin and the native `x` extensions use go-amino for all serialization needs, -including for transactions and accounts. - -### Your Cosmos App - -Your Cosmos App is a fork of Basecoin - copy the `examples/basecoin` directory and modify it to your needs. -You may want to: - -- add fields to accounts -- copy and modify handlers -- add new handlers for new transaction types -- add new stores for better isolation across handlers - -The Cosmos Hub takes Basecoin and adds more stores and extensions to handle additional -transaction types and logic, like the advanced staking logic and the governance process. - -## Ethermint - -Ethermint is a new implementation of `BaseApp` that does not depend on Basecoin. -Instead of `cosmos-sdk/x/` it has its own `ethermint/x` based on `go-ethereum`. - -Ethermint uses a Patricia store for its accounts, and an IAVL store for IBC. -It has `x/ante`, which is quite similar to Basecoin's but uses RLP instead of go-amino. -Instead of `x/bank`, it has `x/eth`, which defines the single Ethereum transaction type -and all the semantics of the Ethereum state machine. - -Within `x/eth`, transactions sent to particular addresses can be handled in unique ways, -for instance to handle IBC and staking. - -# cosmos-sdk-cli - -Create a new application specific blockchain project based on the Cosmos SDK with a single command. - -::: warning -🚧 cosmos-sdk-cli is a work in progress tool to help users scaffold Cosmos SDK applications. It may not be up to date with the latest version and should be considered as experimental. -::: - -## Installation - -```shell -$ go get github.com/cosmos/cosmos-sdk -$ cd $GOPATH/src/github.com/cosmos/cosmos-sdk -$ make install_cosmos-sdk-cli -``` - -This will install a binary `cosmos-sdk-cli` - -## Creating a new project - -```shell -$ cosmos-sdk-cli init <your_project_name> -``` - -This will initialize a project, the dependencies, directory structures with the specified project name. - -### Example: -```shell -$ cosmos-sdk-cli init testzone -p github.com/your_user_name/testzone -``` -`-p [remote-project-path]`. If this is not provided, it creates testzone under `$GOPATH/src/` - -```shell -$ cd $GOPATH/src/github.com/your_user_name/testzone -$ make -``` - -This will create two binaries (`testzonecli` and `testzoned`) under `bin` folder. `testzoned` is the full node of the application which you can run, and `testzonecli` is your light client. diff --git a/docs/spec/README.md b/docs/spec/README.md index 49ea67b7a212..9cb8546be298 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -1,28 +1,31 @@ -# Cosmos Hub Spec +# Specifications -This directory contains specifications for the state transition machine of the -Cosmos Hub. +This directory contains specifications for the modules of the Cosmos SDK as well as Interchain Standards (ICS) and other specifications.. -The Cosmos Hub holds all of its state in a Merkle store. Updates to +SDK applications hold this state in a Merkle store. Updates to the store may be made during transactions and at the beginning and end of every block. -While the first implementation of the Cosmos Hub is built using the Cosmos-SDK, -these specifications aim to be independent of any implementation details. That -said, they provide a detailed resource for understanding the Cosmos-SDK. - -- [Store](store) - The core Merkle store that holds the state. -- [Auth](auth) - The structure and authentication of accounts and transactions. -- [Bank](bank) - Sending tokens. -- [Governance](governance) - Proposals and voting. -- [Staking](staking) - Proof-of-stake bonding, delegation, etc. -- [Slashing](slashing) - Validator punishment mechanisms. -- [Distribution](distribution) - Fee distribution, and atom provision distribution -- [Inflation](inflation) - Atom provision creation -- [IBC](ibc) - Inter-Blockchain Communication (IBC) protocol. -- [Other](other) - Other components of the Cosmos Hub, including the reserve - pool, All in Bits vesting, etc. +### SDK specifications: + +- [Store](./store) - The core Merkle store that holds the state. +- [Bech32](./other/bech32.md) - Address format for Cosmos SDK applications. + +### Modules specifications: + +- [Auth](./auth) - The structure and authentication of accounts and transactions. +- [Bank](./bank) - Sending tokens. +- [Governance](./governance) - Proposals and voting. +- [Staking](./staking) - Proof-of-stake bonding, delegation, etc. +- [Slashing](./slashing) - Validator punishment mechanisms. +- [Distribution](./distribution) - Fee distribution, and staking token provision distribution . +- [Inflation](./inflation) - Staking token provision creation +- [IBC](./ibc) - Inter-Blockchain Communication (IBC) protocol. + +### Interchain standards + +- [ICS30](./ics/ics-030-signed-messages.md) - Signed messages standard. +- For details on the underlying blockchain and p2p protocols, see the [Tendermint specification](https://github.com/tendermint/tendermint/tree/develop/docs/spec). -