cosmos · fedekunze · Oct 28, 2019 · Oct 14, 2019 · Oct 15, 2019 · Oct 16, 2019
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 [![riot.im](https://img.shields.io/badge/riot.im-JOIN%20CHAT-green.svg)](https://riot.im/app/#/room/#cosmos-sdk:matrix.org)
 
 The Cosmos-SDK is a framework for building blockchain applications in Golang.
-It is being used to build `Gaia`, the first implementation of the Cosmos Hub.
+It is being used to build [`Gaia`](https://github.com/cosmos/gaia), the first implementation of the Cosmos Hub.
 
 **WARNING**: The SDK has mostly stabilized, but we are still making some
 breaking changes.
@@ -23,9 +23,9 @@ breaking changes.
 
 To learn how the SDK works from a high-level perspective, go to the [SDK Intro](./docs/intro/intro.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.
+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 repository to get started building your own Cosmos SDK application.
 
-For more, please go to the [Cosmos SDK Docs](./docs/README.md)
+For more, please go to the [Cosmos SDK Docs](./docs/README.md).
 
 ## Cosmos Hub Mainnet
 

diff --git a/docs/README.md b/docs/README.md
@@ -3,20 +3,21 @@
 ## Get Started
 
 - **[SDK Intro](./intro/intro.md)**: High-level overview of the Cosmos SDK.
-- **[SDK application tutorial](https://github.com/cosmos/sdk-application-tutorial)**: A tutorial to learn the SDK. It showcases how to build an SDK-based blockchain from scratch, and explains the basic principles of the SDK in the process.
+- **[SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial)**: A tutorial that showcases how to build an SDK-based blockchain from scratch and explains the basic principles of the SDK in the process.
 
-## Resources
+## Reference
 
-- [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.
+- **[Basics](./basics/README.md)**: Documentation on the basic concepts of the Cosmos SDK, like the standard anatomy of an application, the transaction lifecycle and accounts management.  
+- **[Core](./core/README.md)**: Documentation on the core concepts of the Cosmos SDK, like `baseapp`, the `store` or the `server`. 
+- **[Building Modules](./building-modules/README.md)**: Important concepts for module developers like `message`s, `keeper`s, `handler`s and `querier`s. 
+- **[Interfaces](./interfaces/README.md)**: Documentation on building interfaces for Cosmos SDK applications. 
 
-## Creating a new SDK project
+## Other Resources
 
-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).
+- **[Module Directory](../x/README.md)**: Module implementations and their respective documentation. 
+- **[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
 
@@ -33,6 +34,4 @@ Contact us for information about funding an implementation in another language.
 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:
diff --git a/docs/architecture/README.MD → docs/architecture/README.md b/docs/architecture/README.MD → docs/architecture/README.md
@@ -35,4 +35,4 @@ Please add a entry below in your Pull Request for an ADR.
 - [ADR 006: Secret Store Replacement](./adr-006-secret-store-replacement.md)
 - [ADR 010: Modular AnteHandler](./adr-010-modular-antehandler.md)
 - [ADR 011: Generalize Genesis Accounts](./adr-011-generalize-genesis-accounts.md)
-- [ADR 012: State Accessors](./adr-012-state-accessors.md)
+- [ADR 012: State Accessors](./adr-012-state-accessors.md)
diff --git a/docs/_architecture/adr-002-docs-structure.md → docs/architecture/adr-002-docs-structure.md b/docs/_architecture/adr-002-docs-structure.md → docs/architecture/adr-002-docs-structure.md
diff --git a/docs/_architecture/readme.md → ...architecture/readme.md~origin_master-docs b/docs/_architecture/readme.md → ...architecture/readme.md~origin_master-docs
diff --git a/docs/basics/README.md b/docs/basics/README.md
@@ -0,0 +1,16 @@
+---
+order: false
+parent:
+  order: 2
+---
+
+# Basics
+
+This repository contains reference documentation on the basic concepts of the Cosmos SDK. 
+
+1. [Anatomy of an SDK Application](./app-anatomy.md)
+2. [Lifecycle of a transaction](./tx-lifecycle.md)
+3. [Accounts](./accounts.md)
+4. [Gas and Fees](./gas-fees.md)
+
+After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material. 
diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md
diff --git a/docs/basics/gas-fees.md b/docs/basics/gas-fees.md
@@ -13,7 +13,7 @@ This document describes the default strategies to handle gas and fees within a C
 In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution. `gas` is typically consumed whenever read and writes are made to the store, but it can also be consumed if expensive computation needs to be done. It serves two main purposes:
 
 - Make sure blocks are not consuming too many resources and will be finalized. This is implemented by default in the SDK via the [block gas meter](#block-gas-meter).
-- Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../building-modules/messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). This fee generally has to be paid by the sender of the `message`. Note that the SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler).  
+- Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../building-modules/messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler).  
 
 ## Gas Meter
 
@@ -55,34 +55,34 @@ Gas comsumption can be done manually, generally by the module developer in the [
 
 ### Block Gas Meter
 
-`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`BeginBlock`](../core/baseapp.go#beginblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. 
+`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`BeginBlock`](../core/baseapp.md#beginblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters (by default Cosmos SDK applications use the [default consensus parameters provided by Tendermint](https://github.com/tendermint/tendermint/blob/f323c80cb3b78e123ea6238c8e136a30ff749ccc/types/params.go#L65-L72)). 
 
-When a new [transaction](../core/transaction.md) is being processed via `DeliverTx`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, `DeliverTx` returns immediately. This can happen even with the first transaction in a block, as `BeginBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `DeliverTx`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction:
+When a new [transaction](../core/transactions.md) is being processed via `DeliverTx`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, `DeliverTx` returns immediately. This can happen even with the first transaction in a block, as `BeginBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `DeliverTx`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction:
 
 ```go
 ctx.BlockGasMeter().ConsumeGas(
-				ctx.GasMeter().GasConsumedToLimit(),
-				"block gas meter",
-			)
+	ctx.GasMeter().GasConsumedToLimit(),
+	"block gas meter",
+)
 ```
 
 ## AnteHandler
 
-The `AnteHandler` is a special `handler` that is run for every transaction during `CheckTx` and `DeliverTx`, before the `handler` of each `message` in the transaction. `AnteHandler` have a different signature than `handler`s:
+The `AnteHandler` is a special `handler` that is run for every transaction during `CheckTx` and `DeliverTx`, before the `handler` of each `message` in the transaction. `AnteHandler`s have a different signature than `handler`s:
 
 ```go
 // AnteHandler authenticates transactions, before their internal messages are handled.
 // If newCtx.IsZero(), ctx is used instead.
 type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, result Result, abort bool)
 ```
 
-Being a `handler`, the `anteHandler` is not implemented in the core SDK but in a module. This gives the possibility to developers to choose the version of `AnteHandler` that fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application:
+The `anteHandler` is not implemented in the core SDK but in a module. This gives the possibility to developers to choose which version of `AnteHandler`  fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application:
 
 - Verify that the transaction are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the [transaction interface](https://github.com/cosmos/cosmos-sdk/blob/master/types/tx_msg.go#L34-L41). This enables developers to play with various types for the transaction of their application. In the default `auth` module, the standard transaction type is [`StdTx`](https://github.com/cosmos/cosmos-sdk/blob/master/x/auth/types/stdtx.go#L23-L28).
 - Verify signatures for each [`message`](../building-modules/messages-and-queries.md#messages) contained in the transaction. Each `message` should be signed by one or multiple sender(s), and these signatures must be verified in the `anteHandler`. 
 - During `CheckTx`, verify that the gas prices provided with the transaction is greater than the local `min-gas-prices` (as a reminder, gas-prices can be deducted from the following equation: `fees = gas * gas-prices`). `min-gas-prices` is a parameter local to each full-node and used during `CheckTx` to discard transactions that do not provide a minimum amount of fees. This ensure that the mempool cannot be spammed with garbage transactions. 
 - Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use. 
-- Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is extremely important**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each `DeliverTx` (`ctx` is set to `newCtx` after `anteHandler` is run). 
+- Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is extremely important**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each `DeliverTx` (`ctx` is set to `newCtx` after `anteHandler` is run, and the `anteHandler` is run each time `DeliverTx` is called). 
 
 As explained above, the `anteHandler` returns a maximum limit of `gas` the transaction can consume during execution called `GasWanted`. The actual amount consumed in the end is denominated `GasUsed`, and we must therefore have `GasUsed =< GasWanted`. Both `GasWanted` and `GasUsed` are relayed to the underlying consensus engine when [`DeliverTx`](../core/baseapp.md#delivertx) returns. 
 

diff --git a/docs/basics/readme.md b/docs/basics/readme.md
@@ -2,5 +2,15 @@
 order: false
 parent:
   order: 2
-  title: Basics
 ---
+
+# Basics
+
+This repository contains reference documentation on the basic concepts of the Cosmos SDK. 
+
+1. [Anatomy of an SDK Application](./app-anatomy.md)
+2. [Lifecycle of a transaction](./tx-lifecycle.md)
+3. [Accounts](./accounts.md)
+4. [Gas and Fees](./gas-fees.md)
+
+After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material.