Improve SDK Intro (cosmos#3149)

iammelea · Dec 19, 2018 · d98745f · d98745f
1 parent 7c8a76a
commit d98745f
Show file tree

Hide file tree

Showing 4 changed files with 174 additions and 81 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -2,9 +2,6 @@
 
 Welcome to the SDK docs!
 
-
-![cosmonaut reading the cosmos docs in space](./cosmos-docs.jpg)
-
 ## Learn the SDK
 
 ### SDK Intro
@@ -15,32 +12,36 @@ If you are a newcomer and would like to learn more about the Cosmos SDK, this **
 
 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.
 
-## Use the SDK
-
-The following sections contain the information you need if you want to build a fully-functional SDK-based blockchain:
-
->*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).
-
-- [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). Also contains info on how to join gaia testnets.
-- [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.
-- [SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk): Godocs of the Cosmos-SDK.
-- [REST API spec](https://cosmos.network/rpc/): List of endpoints to interract with a `gaia` full-node through REST.
+### Resources
 
-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!
+- [Specifications](./spec/README.md): Specifications of modules and other parts of the Cosmos SDK. 
+- [SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk): Godocs of the Cosmos SDK.
+- [REST API spec](https://cosmos.network/rpc/): List of endpoints to interact with a `gaia` full-node through REST.
 
 ## Cosmos Hub testnet
 
 To install the latest version of the `gaia` application (application of the Cosmos Hub) and join the public testnet, **click [here](./gaia/join-testnet.md)**
 
 To start your own `gaia` testnet, **click [here](./gaia/deploy-testnet.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. 
+- Use community tools like [chainkit](https://github.com/blocklayerhq/chainkit).
+
+## 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.
+
 ## Contribute
 
 See [this file](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md) for details of the build process and
 considerations when making changes.
 
 ## Version
 
-This documentation is built from the following commit:
+ This documentation is built from the following commit:
diff --git a/docs/intro/README.md b/docs/intro/README.md
@@ -10,34 +10,4 @@ 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-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](./ocap.md).
 
-## Learn more about the SDK
-
-- [SDK application architecture](./sdk-app-architecture.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.
-- `docs/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.
+### Next, learn more about the [SDK Application Architecture](./sdk-app-architecture.md)
diff --git a/docs/intro/sdk-app-architecture.md b/docs/intro/sdk-app-architecture.md
@@ -1,12 +1,67 @@
 # SDK Application Architecture
 
-## Parts of a SDK blockchain
+## State machine 
 
-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.
+At its core, a blockchain application is a [replicated deterministic state machine](https://en.wikipedia.org/wiki/State_machine_replication). 
 
->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).
+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. 
 
-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:
+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/introduction.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 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 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. 
 
 ```
 +---------------------+
@@ -26,37 +81,16 @@ Tendermint passes transactions from the network to the application through an in
 +---------------------+
 ```
 
-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.
+Note that Tendermint only handles transaction bytes. It has no knowledge of what these bytes realy 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 succesful or not. 
 
-Basecoin and the native `x/` extensions use go-amino for all serialization needs, including for transactions and accounts.
+Here are the most important messages of the ABCI:
 
-## SDK tutorial
+- `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. 
 
-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).
+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)