Ethan Buchman
GitHub
commit
bfb2b49b09
|
|
@ -22,7 +22,7 @@ breaking changes.
|
|||
|
||||
## Cosmos Hub Mainnet
|
||||
|
||||
To run a full-node for the mainnet of the Cosmos Hub, first [install `gaia`](./docs/gaia/installation.md), then follow [the guide](./docs/gaia/join-mainnet.md).
|
||||
To run a full-node for the mainnet of the Cosmos Hub, first [install `gaia`](./docs/cosmos-hub/installation.md), then follow [the guide](./docs/cosmos-hub/join-mainnet.md).
|
||||
|
||||
For status updates and genesis file, see the
|
||||
[launch repo](https://github.com/cosmos/launch).
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ module.exports = {
|
|||
collapsable: true,
|
||||
children: [
|
||||
"/intro/",
|
||||
"/intro/sdk-app-architecture",
|
||||
"/intro/sdk-design",
|
||||
"/intro/ocap"
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@
|
|||
|
||||
## Cosmos Hub
|
||||
|
||||
- [Join the mainnet](./gaia/join-mainnet.md) of the Cosmos Hub.
|
||||
- [Join the latest public testnet](./gaia/join-testnet.md) of the Cosmos Hub.
|
||||
- [Start your own `gaia` testnet](./gaia/deploy-testnet.md).
|
||||
- [Join the mainnet](./cosmos-hub/join-mainnet.md) of the Cosmos Hub.
|
||||
- [Join the latest public testnet](./cosmos-hub/join-testnet.md) of the Cosmos Hub.
|
||||
- [Start your own `gaia` testnet](./cosmos-hub/deploy-testnet.md).
|
||||
|
||||
## Creating a new SDK project
|
||||
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ Please exercise extreme caution!
|
|||
[**Download the binaries**]
|
||||
Not available yet.
|
||||
|
||||
[**Install from source**](https://cosmos.network/docs/gaia/installation.html)
|
||||
[**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:
|
||||
|
|
@ -237,7 +237,7 @@ In order to query the state and send transactions, you need a way to access the
|
|||
|
||||
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/gaia/installation.html), and the guide to run a full-node [here](https://cosmos.network/docs/gaia/join-mainnet.html).
|
||||
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
|
||||
|
||||
|
|
@ -286,7 +286,7 @@ gaiacli config trust-node false
|
|||
Finally, let us set the `chain-id` of the blockchain we want to interact with:
|
||||
|
||||
```bash
|
||||
gaiacli config chain-id cosmoshub-1
|
||||
gaiacli config chain-id cosmoshub-2
|
||||
```
|
||||
|
||||
## Querying the State
|
||||
|
|
@ -358,6 +358,24 @@ The transaction `fees` are the product of `gas` and `gasPrice`. As a user, you h
|
|||
For mainnet, the recommended `gas-prices` is `0.025uatom`.
|
||||
:::
|
||||
|
||||
### Sending Tokens
|
||||
|
||||
::: tip
|
||||
**Before you can bond atoms and withdraw rewards, you need to [set up `gaiacli`](#setting-up-gaiacli) and [create an account](#creating-an-account)**
|
||||
:::
|
||||
|
||||
::: warning
|
||||
**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a Ledger Nano S device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).**
|
||||
:::
|
||||
|
||||
```bash
|
||||
// Send a certain amount of tokens to an address
|
||||
// Ex value for parameters (do not actually use these values in your tx!!): <to_address>=cosmos16m93fezfiezhvnjajzrfyszml8qm92a0w67ntjhd3d0 <amount>=1000000uatom
|
||||
// Ex value for flags: <gasPrice>=0.025uatom
|
||||
|
||||
gaiacli tx send <to_address> <amount> --from <yourKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
|
||||
```
|
||||
|
||||
### Bonding Atoms and Withdrawing Rewards
|
||||
|
||||
::: tip
|
||||
|
|
@ -480,10 +498,10 @@ gaiacli tx staking delegate <validatorAddress> <amountToBond> --from <delegatorA
|
|||
|
||||
In order to sign, you will also need the `chain-id`, `account-number` and `sequence`. The `chain-id` is a unique identifier for the blockchain on which you are submitting the transaction. The `account-number` is an identifier generated when your account first receives funds. The `sequence` number is used to keep track of the number of transactions you have sent and prevent replay attacks.
|
||||
|
||||
Get the chain-id from the genesis file (`cosmoshub-1`), and the two other fields using the account query:
|
||||
Get the chain-id from the genesis file (`cosmoshub-2`), and the two other fields using the account query:
|
||||
|
||||
```bash
|
||||
gaiacli query account <yourAddress> --chain-id cosmoshub-1
|
||||
gaiacli query account <yourAddress> --chain-id cosmoshub-2
|
||||
```
|
||||
|
||||
Then, copy `unsignedTx.json` and transfer it (e.g. via USB) to the offline computer. If it is not done already, [create an account on the offline computer](#using-a-computer). For additional security, you can double check the parameters of your transaction before signing it using the following command:
|
||||
|
|
@ -495,7 +513,7 @@ cat unsignedTx.json
|
|||
Now, sign the transaction using the following command. You will need the `chain-id`, `sequence` and `account-number` obtained earlier:
|
||||
|
||||
```bash
|
||||
gaiacli tx sign unsignedTx.json --from <delegatorKeyName> --offline --chain-id cosmoshub-1 --sequence <sequence> --account-number <account-number> > signedTx.json
|
||||
gaiacli tx sign unsignedTx.json --from <delegatorKeyName> --offline --chain-id cosmoshub-2 --sequence <sequence> --account-number <account-number> > signedTx.json
|
||||
```
|
||||
|
||||
Copy `signedTx.json` and transfer it back to the online computer. Finally, use the following command to broadcast the transaction:
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Deploy Your Own Testnet
|
||||
# Deploy Your Own Gaia Testnet
|
||||
|
||||
This document describes 3 ways to setup a network of `gaiad` nodes, each serving a different usecase:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,27 +2,41 @@
|
|||
|
||||
## Gaia CLI
|
||||
|
||||
::: tip Note
|
||||
If you receive this error message:
|
||||
`gaiacli` is the tool that enables you to interact with the node that runs on the Cosmos Hub network, whether you run it yourself or not. Let us set it up properly. In order to install it, follow the [installation procedure](./installation.md).
|
||||
|
||||
### Setting up gaiacli
|
||||
|
||||
The main command used to set up `gaiacli` is the following:
|
||||
|
||||
```bash
|
||||
Must specify these options: --chain-id when --trust-node is false
|
||||
gaiacli config <flag> <value>
|
||||
```
|
||||
|
||||
you must choose whether you wish to verify lite client proofs. If you trust the node which you are querying, you can simply pass `--trust-node=true` - otherwise you'll need to specify `--chain-id`.
|
||||
:::
|
||||
It allows you to set a default value for each given flag.
|
||||
|
||||
`gaiacli` is the command line interface to manage accounts and transactions on Cosmos testnets.
|
||||
Its configuration file resides in `$HOME/.gaiacli/config/config.toml` and can be edited either
|
||||
by hand or via the `gaiacli config` command:
|
||||
First, set up the address of the full-node you want to connect to:
|
||||
|
||||
```bash
|
||||
gaiacli config chain-id gaia-9004
|
||||
gaiacli config node <host>:<port
|
||||
|
||||
// example: gaiacli config node https://77.87.106.33:26657
|
||||
```
|
||||
|
||||
For more information on the command usage, refer to its help screen: `gaiacli config --help`.
|
||||
If you run your own full-node, just use `tcp://localhost:26657` as the address.
|
||||
|
||||
Here is a list of useful `gaiacli` commands, including usage examples.
|
||||
Then, let us set the default value of the `--trust-node` flag:
|
||||
|
||||
```bash
|
||||
gaiacli config trust-node true
|
||||
|
||||
// Set to true if you trust the full-node you are connecting to, false otherwise
|
||||
```
|
||||
|
||||
Finally, let us set the `chain-id` of the blockchain we want to interact with:
|
||||
|
||||
```bash
|
||||
gaiacli config chain-id cosmoshub-2
|
||||
```
|
||||
|
||||
### Keys
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,93 @@
|
|||
# Upgrade Your Node
|
||||
|
||||
This document describes the upgrade procedure of a `gaiad` full-node to a new version.
|
||||
|
||||
## Software Upgrade
|
||||
|
||||
First, stop your instance of `gaiad`. Next, upgrade the software:
|
||||
|
||||
```bash
|
||||
cd $GOPATH/src/github.com/cosmos/cosmos-sdk
|
||||
git fetch --all && git checkout <new_version>
|
||||
make tools install
|
||||
```
|
||||
|
||||
::: tip
|
||||
*NOTE*: If you have issues at this step, please check that you have the latest stable version of GO installed.
|
||||
:::
|
||||
|
||||
See the [testnet repo](https://github.com/cosmos/testnets) for details on which version is needed for which public testnet, and the [SDK release page](https://github.com/cosmos/cosmos-sdk/releases) for details on each release.
|
||||
|
||||
Your full node has been cleanly upgraded!
|
||||
|
||||
## Ugrade Genesis File
|
||||
|
||||
:::warning
|
||||
If the new version you are upgrading to has breaking changes, you will have to restart your chain. If it is not breaking, you can skip to [Restart](#restart)
|
||||
:::
|
||||
|
||||
To upgrade the genesis file, you can either fetch it from a trusted source or export it locally.
|
||||
|
||||
### Fetching from a Trusted Source
|
||||
|
||||
If you are joining the mainnet, fetch the genesis from the [mainnet repo](https://github.com/cosmos/launc). If you are joining a public testnet, fetch the genesis from the appropriate testnet in the [testnet repo](https://github.com/cosmos/testnets). Otherwise, fetch it from your trusted source.
|
||||
|
||||
Save the new genesis as `new_genesis.json`. Then replace the old `genesis.json` with `new_genesis.json`
|
||||
|
||||
```bash
|
||||
cd $HOME/.gaiad/config
|
||||
cp -f genesis.json new-_enesis.json
|
||||
mv new_genesis.json genesis.json
|
||||
```
|
||||
|
||||
Then, go to the [reset data](#reset-data) section.
|
||||
|
||||
### Exporting State to a New Genesis Locally
|
||||
|
||||
If you were running a node in the previous version of the network and want to build your new genesis locally from a state of this previous network, use the following command:
|
||||
|
||||
```bash
|
||||
cd $HOME/.gaiad/config
|
||||
gaiad export --for-zero-height --height=<export-height> > new_genesis.json
|
||||
```
|
||||
|
||||
The command above take a state at a certain height `<export-height>` and turns it into a new genesis file that can be used to start a new network.
|
||||
|
||||
Then, replace the old `genesis.json` with `new_genesis.json`.
|
||||
|
||||
```bash
|
||||
cp -f genesis.json new-_enesis.json
|
||||
mv new_genesis.json genesis.json
|
||||
```
|
||||
|
||||
At this point, you might want to run a script to update the exported genesis into a genesis that is compatible with your new version. For example, the attributes of a the `Account` type changed, a script should query encoded account from the account store, unmarshall them, update their type, re-marhsall and re-store them. You can find an example of such script [here](https://github.com/cosmos/cosmos-sdk/blob/develop/contrib/export/v0.33.x-to-v0.34.0.py).
|
||||
|
||||
## Reset Data
|
||||
|
||||
:::warning
|
||||
If the version <new_version> you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to [Restart](#restart)
|
||||
:::
|
||||
|
||||
::: warning
|
||||
If you are running a **validator node** on the mainnet, always be careful when doing `gaiad unsafe-reset-all`. You should never use this command if you are not switching `chain-id`.
|
||||
:::
|
||||
|
||||
::: danger IMPORTANT
|
||||
Make sure that every node has a unique `priv_validator.json`. Do not copy the `priv_validator.json` from an old node to multiple new nodes. Running two nodes with the same `priv_validator.json` will cause you to get slashed due to double sign !
|
||||
:::
|
||||
|
||||
First, remove the outdated files and reset the data. **If you are running a validator node, make sure you understand what you are doing before resetting**.
|
||||
|
||||
```bash
|
||||
gaiad unsafe-reset-all
|
||||
```
|
||||
|
||||
Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.
|
||||
|
||||
## Restart
|
||||
|
||||
To restart your node, just type:
|
||||
|
||||
```bash
|
||||
gaiad start
|
||||
```
|
||||
|
|
@ -159,7 +159,7 @@ Your validator is active if the following command returns anything:
|
|||
gaiacli query tendermint-validator-set | grep "$(gaiad tendermint show-validator)"
|
||||
```
|
||||
|
||||
You should also be able to see your validator on the [Explorer](https://explorecosmos.network/validators). You are looking for the `bech32` encoded `address` in the `~/.gaiad/config/priv_validator.json` file.
|
||||
You should now see your validator in one of the Cosmos Hub explorers. You are looking for the `bech32` encoded `address` in the `~/.gaiad/config/priv_validator.json` file.
|
||||
|
||||
::: warning Note
|
||||
To be in the validator set, you need to have more total voting power than the 100th validator.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 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 [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk) is a framework for building multi-asset public Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as permissionned 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).
|
||||
|
||||
|
|
@ -10,4 +10,99 @@ It is based on two major principles:
|
|||
|
||||
- **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-capabilities. 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](./ocap.md).
|
||||
|
||||
### Next, learn more about the [SDK Application Architecture](./sdk-app-architecture.md)
|
||||
## SDK Application Architecture
|
||||
|
||||
### State machine
|
||||
|
||||
At its core, a blockchain is a [replicated deterministic state machine](https://en.wikipedia.org/wiki/State_machine_replication).
|
||||
|
||||
A state machine is a computer science concept whereby a machine can have multiple states, but only one at any given time. There is a `state`, which describes the current state of the system, and `transactions`, that trigger state transitions.
|
||||
|
||||
Given a state S and a transaction T, the state machine will return a new state S'.
|
||||
|
||||
```
|
||||
+--------+ +--------+
|
||||
| | | |
|
||||
| S +---------------->+ S' |
|
||||
| | apply(T) | |
|
||||
+--------+ +--------+
|
||||
```
|
||||
|
||||
In practice, the transactions are bundled in blocks to make the process more efficient. Given a state S and a block of transactions B, the state machine will return a new state S'.
|
||||
|
||||
```
|
||||
+--------+ +--------+
|
||||
| | | |
|
||||
| S +----------------------------> | S' |
|
||||
| | For each T in B: apply(T) | |
|
||||
+--------+ +--------+
|
||||
```
|
||||
|
||||
In a blockchain context, the state machine is deterministic. This means that if you start at a given state and replay the same sequence of transactions, you will always end up with the same final state.
|
||||
|
||||
The Cosmos SDK gives you maximum flexibility to define the state of your application, transaction types and state transition functions. The process of building the state-machine with the SDK will be described more in depth in the following sections. But first, let us see how it is replicated using **Tendermint**.
|
||||
|
||||
### Tendermint
|
||||
|
||||
As a developer, you just have to define the state machine using the Cosmos-SDK, and [*Tendermint*](https://tendermint.com/docs/introduction/what-is-tendermint.html) will handle replication over the network for you.
|
||||
|
||||
|
||||
```
|
||||
^ +-------------------------------+ ^
|
||||
| | | | Built with Cosmos SDK
|
||||
| | State-machine = Application | |
|
||||
| | | v
|
||||
| +-------------------------------+
|
||||
| | | ^
|
||||
Blockchain node | | Consensus | |
|
||||
| | | |
|
||||
| +-------------------------------+ | Tendermint Core
|
||||
| | | |
|
||||
| | Networking | |
|
||||
| | | |
|
||||
v +-------------------------------+ v
|
||||
```
|
||||
|
||||
|
||||
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 responsible 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/what-is-tendermint.html).
|
||||
|
||||
Tendermint consensus algorithm works with a set of special nodes called *Validators*. Validators are responsible for adding blocks of transactions to the blockchain. At any given block, there is a validator set V. A validator in V is chosen by the algorithm to be the proposer of the next block. This block is considered valid if more than two thirds of V signed a *[prevote](https://tendermint.com/docs/spec/consensus/consensus.html#prevote-step-height-h-round-r)* and a *[precommit](https://tendermint.com/docs/spec/consensus/consensus.html#precommit-step-height-h-round-r)* on it, and if all the transactions that it contains are valid. The validator set can be changed by rules written in the state-machine. For a deeper look at the algorithm, click [here](https://tendermint.com/docs/introduction/what-is-tendermint.html#consensus-overview).
|
||||
|
||||
|
||||
The main part of a Cosmos SDK application is a blockchain daemon that is run by each node in the network locally. If less than one third of the *validator set* is byzantine (i.e. malicious), then each node should obtain the same result when querying the state at the same time.
|
||||
|
||||
## ABCI
|
||||
|
||||
Tendermint passes transactions from the network to the application through an interface called the [ABCI](https://github.com/tendermint/tendermint/tree/master/abci), which the application must implement.
|
||||
|
||||
```
|
||||
+---------------------+
|
||||
| |
|
||||
| Application |
|
||||
| |
|
||||
+--------+---+--------+
|
||||
^ |
|
||||
| | ABCI
|
||||
| v
|
||||
+--------+---+--------+
|
||||
| |
|
||||
| |
|
||||
| Tendermint |
|
||||
| |
|
||||
| |
|
||||
+---------------------+
|
||||
```
|
||||
|
||||
Note that **Tendermint only handles transaction bytes**. It has no knowledge of what these bytes mean. All Tendermint does is order these transaction bytes deterministically. Tendermint passes the bytes to the application via the ABCI, and expects a return code to inform it if the messages contained in the transactions were successfully processed or not.
|
||||
|
||||
Here are the most important messages of the ABCI:
|
||||
|
||||
- `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam. A special handler called the "Ante Handler" is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the check is valid, the transaction is added to the [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet.
|
||||
- `DeliverTx`: When a [valid block](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation) is received by Tendermint Core, each transaction in the given block is passed to the application via `DeliverTx` to be processed. It is during this stage that the state transitions occur. The "Ante Handler" executes again along with the actual handlers for each message in the transaction.
|
||||
- `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transaction or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite.
|
||||
|
||||
For a more detailed view of the ABCI methods and types, click [here](https://tendermint.com/docs/spec/abci/abci.html#overview).
|
||||
|
||||
Any application built on Tendermint needs to implement the ABCI interface in order to communicate with the underlying local Tendermint engine. Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](./sdk-design.md#baseapp).
|
||||
|
||||
### Next, let us go into the [high-level design principles of the SDK](./sdk-design.md)
|
||||
|
|
@ -1,96 +0,0 @@
|
|||
# SDK Application Architecture
|
||||
|
||||
## State machine
|
||||
|
||||
At its core, a blockchain application is a [replicated deterministic state machine](https://en.wikipedia.org/wiki/State_machine_replication).
|
||||
|
||||
A state machine is a computer science concept whereby a machine can have multiple states, but only one at any given time. There is a state, which describes the current state of the system, and transactions, that trigger state transitions.
|
||||
|
||||
Given a state S and a transaction T, the state machine will return a new state S'.
|
||||
|
||||
```
|
||||
+--------+ +--------+
|
||||
| | | |
|
||||
| S +---------------->+ S' |
|
||||
| | apply(T) | |
|
||||
+--------+ +--------+
|
||||
```
|
||||
|
||||
In practice, the transactions are bundled in blocks to make the process more efficient. Given a state S and a block of transactions B, the state machine will return a new state S'.
|
||||
|
||||
```
|
||||
+--------+ +--------+
|
||||
| | | |
|
||||
| S +----------------------------> | S' |
|
||||
| | For each T in B: apply(T) | |
|
||||
+--------+ +--------+
|
||||
```
|
||||
|
||||
In a blockchain context, the state machine is deterministic. This means that if you start at a given state and replay the same sequence of transactions, you will always end up with the same final state.
|
||||
|
||||
The Cosmos SDK gives you maximum flexibility to define the state of your application, transaction types and state-transition functions. The process of building the state-machine with the SDK will be described more in depth in the following sections. But first, let us see how it is replicated using **Tendermint**.
|
||||
|
||||
## Tendermint
|
||||
|
||||
As a developer, you just have to define the state machine using the Cosmos-SDK, and [*Tendermint*](https://tendermint.com/docs/introduction/what-is-tendermint.html) will handle replication over the network for you.
|
||||
|
||||
|
||||
```
|
||||
^ +-------------------------------+ ^
|
||||
| | | | Built with Cosmos SDK
|
||||
| | State-machine = Application | |
|
||||
| | | v
|
||||
| +-------------------------------+
|
||||
| | | ^
|
||||
Blockchain node | | Consensus | |
|
||||
| | | |
|
||||
| +-------------------------------+ | Tendermint Core
|
||||
| | | |
|
||||
| | Networking | |
|
||||
| | | |
|
||||
v +-------------------------------+ v
|
||||
```
|
||||
|
||||
|
||||
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 responsible 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/what-is-tendermint.html).
|
||||
|
||||
Tendermint consensus algorithm works with a set of special nodes called *Validators*. Validators are responsible for adding blocks of transactions to the blockchain. At any given block, there is a validator set V. A validator in V is chosen by the algorithm to be the proposer of the next block. This block is considered valid if more than two thirds of V signed a *[prevote](https://tendermint.com/docs/spec/consensus/consensus.html#prevote-step-height-h-round-r)* and a *[precommit](https://tendermint.com/docs/spec/consensus/consensus.html#precommit-step-height-h-round-r)* on it, and if all the transactions that it contains are valid. The validator set can be changed by rules written in the state-machine. For a deeper look at the algorithm, click [here](https://tendermint.com/docs/introduction/what-is-tendermint.html#consensus-overview).
|
||||
|
||||
|
||||
The main part of a Cosmos SDK application is a blockchain daemon that is run by each node in the network locally. If less than one third of the *validator set* is byzantine (i.e. malicious), then each node should obtain the same result when querying the state at the same time.
|
||||
|
||||
## ABCI
|
||||
|
||||
Tendermint passes transactions from the network to the application through an interface called the [ABCI](https://github.com/tendermint/tendermint/tree/master/abci), which the application must implement.
|
||||
|
||||
```
|
||||
+---------------------+
|
||||
| |
|
||||
| Application |
|
||||
| |
|
||||
+--------+---+--------+
|
||||
^ |
|
||||
| | ABCI
|
||||
| v
|
||||
+--------+---+--------+
|
||||
| |
|
||||
| |
|
||||
| Tendermint |
|
||||
| |
|
||||
| |
|
||||
+---------------------+
|
||||
```
|
||||
|
||||
Note that Tendermint only handles transaction bytes. It has no knowledge of what these bytes really mean. All Tendermint does is to order them deterministically. It is the job of the application to give meaning to these bytes. Tendermint passes the bytes to the application via the ABCI, and expects a return code to inform it if the message was successful or not.
|
||||
|
||||
Here are the most important messages of the ABCI:
|
||||
|
||||
- `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check its validity. A special handler called the "Ante Handler" is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the transaction is valid, the transaction is added to the [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet.
|
||||
- `DeliverTx`: When a [valid block](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation) is received by Tendermint Core, each transaction in the given block is passed to the application via `DeliverTx` to be processed. It is during this stage where the state transitions occur. The "Ante Handler" executes again along with the actual handlers for each message in the transaction.
|
||||
- `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transaction or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite.
|
||||
|
||||
For a more detailed view of the ABCI methods and types, click [here](https://tendermint.com/docs/spec/abci/abci.html#overview).
|
||||
|
||||
Any application built on Tendermint needs to implement the ABCI interface in order to communicate with the underlying local Tendermint engine. Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](./sdk-design.md#baseapp).
|
||||
|
||||
### Next, let us go into the [high-level design principles of the SDK](./sdk-design.md)
|
||||
|
|
@ -2,13 +2,12 @@
|
|||
|
||||
The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of Tendermint. At its core, the SDK is a boilerplate implementation of the ABCI in Golang. It comes with a `multistore` to persist data and a `router` to handle transactions.
|
||||
|
||||
Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from Tendermint via `DeliverTx`
|
||||
(the `CheckTx` process is the same without enforcing state changes):
|
||||
Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from Tendermint via `DeliverTx`:
|
||||
|
||||
1. Decode transactions received from the Tendermint consensus engine (remember that Tendermint only deals with `[]bytes`).
|
||||
2. Extract messages from transactions and do basic sanity checks.
|
||||
1. Decode `transactions` received from the Tendermint consensus engine (remember that Tendermint only deals with `[]bytes`).
|
||||
2. Extract `messages` from `transactions` and do basic sanity checks.
|
||||
3. Route each message to the appropriate module so that it can be processed.
|
||||
4. Commit the state changes.
|
||||
4. Commit state changes.
|
||||
|
||||
The application also enables you to generate transactions, encode them and pass them to the underlying Tendermint engine to broadcast them.
|
||||
|
||||
|
|
@ -16,7 +15,7 @@ The application also enables you to generate transactions, encode them and pass
|
|||
|
||||
`baseApp` is the boilerplate implementation of the ABCI of the Cosmos SDK. It comes with a `router` to route transactions to their respective module. The main `app.go` file of your application will define your custom `app` type that will embed `baseapp`. This way, your custom `app` type will automatically inherit all the ABCI methods of `baseapp`. See an example of this in the [SDK application tutorial](https://github.com/cosmos/sdk-application-tutorial/blob/master/app.go#L27).
|
||||
|
||||
The goal of `baseapp` 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).
|
||||
The goal of `baseapp` is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible (staying true to the ABCI).
|
||||
|
||||
For more on `baseapp`, please click [here](../concepts/baseapp.md).
|
||||
|
||||
|
|
@ -30,11 +29,14 @@ The multistore abstraction is used to divide the state in distinct compartments,
|
|||
|
||||
The power of the Cosmos SDK lies in its modularity. SDK applications are built by aggregating a collection of interoperable modules. Each module defines a subset of the state and contains its own message/transaction processor, while the SDK is responsible for routing each message to its respective module.
|
||||
|
||||
Here is a simplified view of how a transaction is processed by the application of each full-node when it is received in a valid block:
|
||||
|
||||
```
|
||||
+
|
||||
|
|
||||
| Transaction relayed from Tendermint
|
||||
| via DeliverTx
|
||||
| Transaction relayed from the full-node's Tendermint engine
|
||||
| to the node's application via DeliverTx
|
||||
|
|
||||
|
|
||||
|
|
||||
+---------------------v--------------------------+
|
||||
|
|
@ -74,7 +76,7 @@ The power of the Cosmos SDK lies in its modularity. SDK applications are built b
|
|||
v
|
||||
```
|
||||
|
||||
Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* Messages are extracted from transactions in `baseapp`'s methods). In general, each module declares its own `KVStore` in the multistore to persist the subset of the state it defines. 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-capabilities](./ocap.md). 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.
|
||||
Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` using `baseapp`). In general, each module declares its own `KVStore` in the multistore to persist the subset of the state it defines. 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-capabilities](./ocap.md). 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.
|
||||
|
||||
SDK modules are defined in the `x/` folder of the SDK. Some core modules include:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue