Merge PR cosmos#4691: Add baseapp concept doc

* consolidate intro * start anatomy of sdk app * wokring * working * querier * working * workiiiing * finish * add dep and makefile * Apply suggestions from code review Co-Authored-By: Alessio Treglia <[email protected]> * typo * typo * Apply suggestions from code review Co-Authored-By: Alexander Bezobchuk <[email protected]> Co-Authored-By: Federico Kunze <[email protected]> Co-Authored-By: Alessio Treglia <[email protected]> Co-Authored-By: frog power 4000 <[email protected]> * refactor for new module interface * karoly review * Apply suggestions from code review Co-Authored-By: Karoly Albert Szabo <[email protected]> Co-Authored-By: Federico Kunze <[email protected]> * encoding * working on baseapp doc * baseapp work * reorg * almost there * finish first draft * remove old files * hans review' * jack review + clarification on ABCI methods
augchan42 · Jul 17, 2019 · ae77f00 · ae77f00
1 parent 8c7ed19
commit ae77f00
Show file tree

Hide file tree

Showing 52 changed files with 362 additions and 10 deletions.
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/basics/accounts-fees-gas.md b/docs/basics/accounts-fees-gas.md
@@ -0,0 +1,15 @@
+# Accounts, Fees and Gas
+
+## Accounts
+
+## AnteHandler
+
+## Signatures
+
+## Fees
+
+## Gas
+
+## Gas Meter
+
+## Block Gas Meter
diff --git a/docs/concepts/app-anatomy.md → docs/basics/app-anatomy.md b/docs/concepts/app-anatomy.md → docs/basics/app-anatomy.md
@@ -117,7 +117,7 @@ The SDK offers developers the possibility to implement automatic execution of co
 
 In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the `BeginBlock` and `EndBlock` functions of each of the application's modules. This is done by calling the `BeginBlock` and `EndBlock` functions of the module manager, which in turn will call the `BeginBLock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BegingBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlock` and `SetOrderEndBlock` methods respectively. This is done in the [application's constructor](#application-constructor), and the `SetOrderBeginBlock` and `SetOrderEndBlock` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions.
 
-As a sidenote, it is important to remember that application-specific blockchains are deterministic. Developers must be careful not to introduce non-determinism in `BeginBlocker` or `EndBlocker`, and must also be careful not to make them too computationally expensive, as [gas](./fees-signature.md/gas) does not constrain the cost of `BeginBlocker` and `EndBlocker` execution. 
+As a sidenote, it is important to remember that application-specific blockchains are deterministic. Developers must be careful not to introduce non-determinism in `BeginBlocker` or `EndBlocker`, and must also be careful not to make them too computationally expensive, as [gas](./accounts-fees-gas.md/gas) does not constrain the cost of `BeginBlocker` and `EndBlocker` execution. 
 
 You can see an example of `BeginBlocker` and `EndBlocker` functions [here](https://github.com/cosmos/gaia/blob/master/app/app.go#L224-L232).
 
@@ -155,7 +155,7 @@ To learn more about the application module interface, [click here](./modules.md#
 A message is a custom type defined by each module that implements the [`message`](https://github.com/cosmos/cosmos-sdk/blob/master/types/tx_msg.go#L8-L29) interface. Each `transaction` contains one or multiple `messages`. When a valid block of transactions is received by the full-node, Tendermint relays each one to the application via [`DeliverTx`](https://tendermint.com/docs/app-dev/abci-spec.html#delivertx). Then, the application handles the transaction:
 
 1. Upon receiving the transaction, the application first unmarshalls it from `[]bytes`.
-2. Then, it verifies a few things about the transaction like [fee payment and signatures](#fees-signature.md) before extracting the message(s) contained in the transaction. 
+2. Then, it verifies a few things about the transaction like [fee payment and signatures](#accounts-fees-gas.md) before extracting the message(s) contained in the transaction. 
 3. With the [`Type()`](https://github.com/cosmos/cosmos-sdk/blob/master/types/tx_msg.go#L16) method, `baseapp` is able to know which modules defines the message. It is then able to route it to the appropriate module's [handler](#handler) in order for the message to be processed. 
 4. If the message is successfully processed, the state is updated. 
 

diff --git a/docs/concepts/tx-lifecycle.md → docs/basics/tx-lifecycle.md b/docs/concepts/tx-lifecycle.md → docs/basics/tx-lifecycle.md
diff --git a/docs/modules/README.md → docs/building-modules.md/README.md b/docs/modules/README.md → docs/building-modules.md/README.md
diff --git a/docs/concepts/handler.md → docs/building-modules.md/handler.md b/docs/concepts/handler.md → docs/building-modules.md/handler.md
diff --git a/docs/concepts/invariants.md → docs/building-modules.md/invariants.md b/docs/concepts/invariants.md → docs/building-modules.md/invariants.md
diff --git a/docs/concepts/keeper.md → docs/building-modules.md/keeper.md b/docs/concepts/keeper.md → docs/building-modules.md/keeper.md
diff --git a/docs/concepts/module-interfaces.md → .../building-modules.md/module-interfaces.md b/docs/concepts/module-interfaces.md → .../building-modules.md/module-interfaces.md
diff --git a/docs/concepts/modules.md → docs/building-modules.md/modules.md b/docs/concepts/modules.md → docs/building-modules.md/modules.md
diff --git a/docs/concepts/querier.md → docs/building-modules.md/querier.md b/docs/concepts/querier.md → docs/building-modules.md/querier.md
diff --git a/docs/concepts/fees-signature.md b/docs/concepts/fees-signature.md
diff --git a/docs/core/baseapp.md b/docs/core/baseapp.md
diff --git a/docs/concepts/baseapp.md → docs/core/baseapp_old.md b/docs/concepts/baseapp.md → docs/core/baseapp_old.md
diff --git a/docs/concepts/store/README.md → docs/core/context.md b/docs/concepts/store/README.md → docs/core/context.md
diff --git a/docs/concepts/encoding.md → docs/core/encoding.md b/docs/concepts/encoding.md → docs/core/encoding.md
diff --git a/docs/concepts/genesis.md → docs/core/genesis.md b/docs/concepts/genesis.md → docs/core/genesis.md
diff --git a/docs/concepts/node.md → docs/core/node.md b/docs/concepts/node.md → docs/core/node.md
diff --git a/docs/intro/ocap.md → docs/core/ocap.md b/docs/intro/ocap.md → docs/core/ocap.md
diff --git a/docs/core/store.md b/docs/core/store.md
@@ -0,0 +1,8 @@
+# Store
+
+## Commit Multi Store
+
+## Database 
+
+## Main Store
+
diff --git a/docs/core/tx-msgs.md b/docs/core/tx-msgs.md
@@ -0,0 +1,5 @@
+# Transactions and Messages
+
+## Transactions
+
+## Messages
diff --git a/docs/clients/README.md → docs/interfaces/README.md b/docs/clients/README.md → docs/interfaces/README.md
diff --git a/docs/clients/cli.md → docs/interfaces/cli.md b/docs/clients/cli.md → docs/interfaces/cli.md
diff --git a/docs/concepts/interfaces.md → docs/interfaces/interfaces.md b/docs/concepts/interfaces.md → docs/interfaces/interfaces.md
diff --git a/docs/clients/lite/getting_started.md → docs/interfaces/lite/getting_started.md b/docs/clients/lite/getting_started.md → docs/interfaces/lite/getting_started.md
diff --git a/docs/clients/lite/pics/C2H.png → docs/interfaces/lite/pics/C2H.png b/docs/clients/lite/pics/C2H.png → docs/interfaces/lite/pics/C2H.png
diff --git a/docs/clients/lite/pics/H2C.png → docs/interfaces/lite/pics/H2C.png b/docs/clients/lite/pics/H2C.png → docs/interfaces/lite/pics/H2C.png
diff --git a/docs/clients/lite/pics/MA.png → docs/interfaces/lite/pics/MA.png b/docs/clients/lite/pics/MA.png → docs/interfaces/lite/pics/MA.png
diff --git a/docs/clients/lite/pics/absence1.png → docs/interfaces/lite/pics/absence1.png b/docs/clients/lite/pics/absence1.png → docs/interfaces/lite/pics/absence1.png
diff --git a/docs/clients/lite/pics/absence2.png → docs/interfaces/lite/pics/absence2.png b/docs/clients/lite/pics/absence2.png → docs/interfaces/lite/pics/absence2.png
diff --git a/docs/clients/lite/pics/absence3.png → docs/interfaces/lite/pics/absence3.png b/docs/clients/lite/pics/absence3.png → docs/interfaces/lite/pics/absence3.png
diff --git a/docs/clients/lite/pics/architecture.png → docs/interfaces/lite/pics/architecture.png b/docs/clients/lite/pics/architecture.png → docs/interfaces/lite/pics/architecture.png
diff --git a/docs/clients/lite/pics/changeProcess.png → docs/interfaces/lite/pics/changeProcess.png b/docs/clients/lite/pics/changeProcess.png → docs/interfaces/lite/pics/changeProcess.png
diff --git a/docs/clients/lite/pics/commitValidation.png → ...interfaces/lite/pics/commitValidation.png b/docs/clients/lite/pics/commitValidation.png → ...interfaces/lite/pics/commitValidation.png
diff --git a/docs/clients/lite/pics/create-account.png → docs/interfaces/lite/pics/create-account.png b/docs/clients/lite/pics/create-account.png → docs/interfaces/lite/pics/create-account.png
diff --git a/docs/clients/lite/pics/deposit.png → docs/interfaces/lite/pics/deposit.png b/docs/clients/lite/pics/deposit.png → docs/interfaces/lite/pics/deposit.png
diff --git a/docs/clients/lite/pics/existProof.png → docs/interfaces/lite/pics/existProof.png b/docs/clients/lite/pics/existProof.png → docs/interfaces/lite/pics/existProof.png
diff --git a/docs/clients/lite/pics/high-level.png → docs/interfaces/lite/pics/high-level.png b/docs/clients/lite/pics/high-level.png → docs/interfaces/lite/pics/high-level.png
diff --git a/...s/lite/pics/light-client-architecture.png → ...s/lite/pics/light-client-architecture.png b/...s/lite/pics/light-client-architecture.png → ...s/lite/pics/light-client-architecture.png
diff --git a/.../clients/lite/pics/loadbalanceDiagram.png → ...terfaces/lite/pics/loadbalanceDiagram.png b/.../clients/lite/pics/loadbalanceDiagram.png → ...terfaces/lite/pics/loadbalanceDiagram.png
diff --git a/docs/clients/lite/pics/simpleMerkleTree.png → ...interfaces/lite/pics/simpleMerkleTree.png b/docs/clients/lite/pics/simpleMerkleTree.png → ...interfaces/lite/pics/simpleMerkleTree.png
diff --git a/docs/clients/lite/pics/substoreProof.png → docs/interfaces/lite/pics/substoreProof.png b/docs/clients/lite/pics/substoreProof.png → docs/interfaces/lite/pics/substoreProof.png
diff --git a/docs/clients/lite/pics/transfer-tokens.png → .../interfaces/lite/pics/transfer-tokens.png b/docs/clients/lite/pics/transfer-tokens.png → .../interfaces/lite/pics/transfer-tokens.png
diff --git a/docs/clients/lite/pics/transfer.png → docs/interfaces/lite/pics/transfer.png b/docs/clients/lite/pics/transfer.png → docs/interfaces/lite/pics/transfer.png
diff --git a/docs/clients/lite/pics/trustPropagate.png → docs/interfaces/lite/pics/trustPropagate.png b/docs/clients/lite/pics/trustPropagate.png → docs/interfaces/lite/pics/trustPropagate.png
diff --git a/...nts/lite/pics/updateValidatorToHeight.png → ...ces/lite/pics/updateValidatorToHeight.png b/...nts/lite/pics/updateValidatorToHeight.png → ...ces/lite/pics/updateValidatorToHeight.png
diff --git a/.../clients/lite/pics/validatorSetChange.png → ...terfaces/lite/pics/validatorSetChange.png b/.../clients/lite/pics/validatorSetChange.png → ...terfaces/lite/pics/validatorSetChange.png
diff --git a/docs/clients/lite/pics/withdraw.png → docs/interfaces/lite/pics/withdraw.png b/docs/clients/lite/pics/withdraw.png → docs/interfaces/lite/pics/withdraw.png
diff --git a/docs/clients/lite/readme.md → docs/interfaces/lite/readme.md b/docs/clients/lite/readme.md → docs/interfaces/lite/readme.md
diff --git a/docs/clients/lite/specification.md → docs/interfaces/lite/specification.md b/docs/clients/lite/specification.md → docs/interfaces/lite/specification.md
diff --git a/docs/clients/service-providers.md → docs/interfaces/service-providers.md b/docs/clients/service-providers.md → docs/interfaces/service-providers.md
diff --git a/docs/intro/sdk-design.md b/docs/intro/sdk-design.md
@@ -76,7 +76,7 @@ Here is a simplified view of how a transaction is processed by the application o
                                        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` 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. 
+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](../coore/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:
-Original file line number
+Diff line change
@@ Expand Up @@
                                            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` 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.
+    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](../coore/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:
@@ Expand Down @@