docs: improve IBC guide (#6472)

* docs: improve IBC guide * remove module specs * capability spec * update capability spec * move cap to concepts * remove module specs * split IBC section * wip integration.md * complete integration.md * format integration.md * docs updates * Apply suggestions from code review Co-authored-by: colin axner <25233464+colin-axner@users.noreply.github.com> * fix Next links * further readings Co-authored-by: colin axner <25233464+colin-axner@users.noreply.github.com>
Finschia · Jul 7, 2020 · be194ca · be194ca
1 parent 7fdcdc1
commit be194ca
Show file tree

Hide file tree

Showing 19 changed files with 962 additions and 412 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,6 +17,7 @@ examples/build/*
 docs/_build
 docs/tutorial
 docs/node_modules
+docs/modules
 dist
 tools-stamp
 proto-tools-stamp

diff --git a/docs/Screen Shot 2019-10-17 at 15.07.22.png b/docs/Screen Shot 2019-10-17 at 15.07.22.png
diff --git a/docs/building-modules/README.md b/docs/building-modules/README.md
@@ -1,7 +1,7 @@
 <!--
 order: false
 parent:
-  order: 4
+  order: 5
 -->
 
 # Building Modules

diff --git a/docs/core/README.md b/docs/core/README.md
@@ -16,8 +16,8 @@ This repository contains reference documentation on the core concepts of the Cos
 6. [Encoding](./encoding.md)
 7. [Events](./events.md)
 8. [Telemetry](./telemetry.md)
-9  [IBC](./ibc.md)
-10.[Object-Capabilities](./ocap.md)
-11.[RunTx recovery middleware](./runtx_middleware.md)
+9. [Object-Capabilities](./ocap.md)
+10. [RunTx recovery middleware](./runtx_middleware.md)
 
-After reading about the core concepts, head on to the [Building Modules documentation](../building-modules/README.md) to learn more about the process of building modules.
+After reading about the core concepts, check the [IBC documentation](../ibc/README.md) to learn more
+about the IBC core concepts and how to integrate it to you application.
diff --git a/docs/core/events.md b/docs/core/events.md
@@ -109,8 +109,8 @@ The `type` and `attribute` value of the `query` allow you to filter the specific
 }
 ```
 
-where `senderAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format. 
+where `senderAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format.
 
 ## Next {hide}
 
-Learn about [object-capabilities](./ocap.md) {hide}
+Learn about SDK [telemetry](./telemetry.md) {hide}
diff --git a/docs/core/ibc.md b/docs/core/ibc.md
diff --git a/docs/core/ocap.md b/docs/core/ocap.md
@@ -1,5 +1,5 @@
 <!--
-order: 10
+order: 9
 -->
 
 # Object-Capability Model
@@ -39,7 +39,7 @@ foundation of an object capability system.
 >     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](https://en.wikipedia.org/wiki/Object-capability_model).
+For an introduction to object-capabilities, see this [Wikipedia article](https://en.wikipedia.org/wiki/Object-capability_model).
 
 ## Ocaps in practice
 
@@ -50,26 +50,26 @@ principle:
 
 ```go
 type AppAccount struct {...}
-var account := &AppAccount{
+account := &AppAccount{
     Address: pub.Address(),
     Coins: sdk.Coins{sdk.NewInt64Coin("ATM", 100)},
 }
-var sumValue := externalModule.ComputeSumValue(account)
+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)
+sumValue := externalModule.ComputeSumValue(*account)
 ```
 
 In the Cosmos SDK, you can see the application of this principle in the
 gaia app.
 
 +++ https://github.com/cosmos/gaia/blob/master/app/app.go#L197-L209
 
-## Next
+## Next {hide}
 
-Learn about [building modules](../building-modules/intro.md) {hide}
+Learn about the [`runTx` middleware](./runtx_middleware.md) {hide}
diff --git a/docs/core/runtx_middleware.md b/docs/core/runtx_middleware.md
@@ -1,5 +1,5 @@
 <!--
-order: 11
+order: 10
 -->
 
 # RunTx recovery middleware
@@ -10,7 +10,7 @@ Recovery middleware is used to add custom panic recovery for SDK application dev
 
 More context could be found in the corresponding [ADR-022](../architecture/adr-022-custom-panic-handling.md).
 
-Implementation could be found in the [recovery.go](../../baseapp/recovery.go) file. 
+Implementation could be found in the [recovery.go](../../baseapp/recovery.go) file.
 
 ## Interface
 
@@ -21,46 +21,53 @@ type RecoveryHandler func(recoveryObj interface{}) error
 `recoveryObj` is a return value for `recover()` function from the `buildin` Golang package.
 
 **Contract:**
+
 * RecoveryHandler returns `nil` if `recoveryObj` wasn't handled and should be passed to the next recovery middleware;
 * RecoveryHandler returns a non-nil `error` if `recoveryObj` was handled;
 
 ## Custom RecoveryHandler register
 
 ``BaseApp.AddRunTxRecoveryHandler(handlers ...RecoveryHandler)``
 
-BaseApp method adds recovery middleware to the default recovery chain. 
+BaseApp method adds recovery middleware to the default recovery chain.
 
 ## Example
 
 Lets assume we want to emit the "Consensus failure" chain state if some particular error occurred.
 
 We have a module keeper that panics:
+
 ```go
 func (k FooKeeper) Do(obj interface{}) {
     if obj == nil {
         // that shouldn't happen, we need to crash the app
         err := sdkErrors.Wrap(fooTypes.InternalError, "obj is nil")
         panic(err)
     }
-} 
+}
 ```
 
 By default that panic would be recovered and an error message will be printed to log. To override that behaviour we should register a custom RecoveryHandler:
+
 ```go
 // SDK application constructor
 customHandler := func(recoveryObj interface{}) error {
     err, ok := recoveryObj.(error)
     if !ok {
         return nil
     }
-    
+
     if fooTypes.InternalError.Is(err) {
-    	panic(fmt.Errorf("FooKeeper did panic with error: %w", err))
+        panic(fmt.Errorf("FooKeeper did panic with error: %w", err))
     }
-    
+
     return nil
 }
 
 baseApp := baseapp.NewBaseApp(...)
 baseApp.AddRunTxRecoveryHandler(customHandler)
 ```
+
+## Next {hide}
+
+Learn about the [IBC](./../ibc/README.md) protocol {hide}
diff --git a/docs/core/telemetry.md b/docs/core/telemetry.md
@@ -4,6 +4,8 @@ order: 8
 
 # Telemetry
 
+Gather relevant insights about your application and modules with custom metrics and telemetry. {synopsis}
+
 The Cosmos SDK enables operators and developers to gain insight into the performance and behavior of
 their application through the use of the `telemetry` package. The Cosmos SDK currently supports
 enabling in-memory and prometheus as telemetry sinks. This allows the ability to query for and scrape
@@ -75,7 +77,7 @@ The following examples expose too much cardinality and may not even prove to be
 ## Supported Metrics
 
 | Metric                          | Description                                                                            | Unit         | Type    |
-| :------------------------------ | :------------------------------------------------------------------------------------- | :----------- | :------ |
+|:--------------------------------|:---------------------------------------------------------------------------------------|:-------------|:--------|
 | `tx_count`                      | Total number of txs processed via `DeliverTx`                                          | tx           | counter |
 | `tx_successful`                 | Total number of successful txs processed via `DeliverTx`                               | tx           | counter |
 | `tx_failed`                     | Total number of failed txs processed via `DeliverTx`                                   | tx           | counter |
@@ -116,3 +118,7 @@ The following examples expose too much cardinality and may not even prove to be
 | `store_cachekv_set`             | Duration of a CacheKV `Store#Set` call                                                 | ms           | summary |
 | `store_cachekv_write`           | Duration of a CacheKV `Store#Write` call                                               | ms           | summary |
 | `store_cachekv_delete`          | Duration of a CacheKV `Store#Delete` call                                              | ms           | summary |
+
+## Next {hide}
+
+Learn about the [object-capability](./ocap.md) model {hide}
diff --git a/docs/core/transactions.md b/docs/core/transactions.md
@@ -45,13 +45,13 @@ When users interact with the application's interfaces, they invoke the underlyin
 
 ### Messages
 
-**`Message`s** are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the `message`s for their module by implementing the `Msg` interface, and also define a [`Handler`](../building-modules/handler.md) to process them. 
+**`Message`s** are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the `message`s for their module by implementing the `Msg` interface, and also define a [`Handler`](../building-modules/handler.md) to process them.
 
 +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/tx_msg.go#L8-L29
 
 `Message`s in a module are typically defined in a `msgs.go` file (though not always), and one handler with multiple functions to handle each of the module's `message`s is defined in a `handler.go` file.
 
-Note: module `messages` are not to be confused with [ABCI Messages](https://tendermint.com/docs/spec/abci/abci.html#messages) which define interactions between the Tendermint and application layers. 
+Note: module `messages` are not to be confused with [ABCI Messages](https://tendermint.com/docs/spec/abci/abci.html#messages) which define interactions between the Tendermint and application layers.
 
 To learn more about `message`s, click [here](../building-modules/messages-and-queries.md#messages).
 
@@ -67,17 +67,17 @@ The `TxBuilder` contains data closely related with the processing of transaction
 
 +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/types/txbuilder.go#L18-L31
 
-- `TxEncoder` defined by the developer for this type of transaction. Used to encode messages before being processed by nodes running Tendermint.
-- `Keybase` that manages the user's keys and is used to perform signing operations.
-- `AccountNumber` from which this transaction originated.
-- `Sequence`, the number of transactions that the user has sent out, used to prevent replay attacks.
-- `Gas` option chosen by the users for how to calculate how much gas they will need to pay. A common option is "auto" which generates an automatic estimate.
-- `GasAdjustment` to adjust the estimate of gas by a scalar value, used to avoid underestimating the amount of gas required.
-- `SimulateAndExecute` option to simply simulate the transaction execution without broadcasting.
-- `ChainID` representing which blockchain this transaction pertains to.
-- `Memo` to send with the transaction.
-- `Fees`, the maximum amount the user is willing to pay in fees. Alternative to specifying gas prices.
-- `GasPrices`, the amount per unit of gas the user is willing to pay in fees. Alternative to specifying fees.
+* `TxEncoder` defined by the developer for this type of transaction. Used to encode messages before being processed by nodes running Tendermint.
+* `Keybase` that manages the user's keys and is used to perform signing operations.
+* `AccountNumber` from which this transaction originated.
+* `Sequence`, the number of transactions that the user has sent out, used to prevent replay attacks.
+* `Gas` option chosen by the users for how to calculate how much gas they will need to pay. A common option is "auto" which generates an automatic estimate.
+* `GasAdjustment` to adjust the estimate of gas by a scalar value, used to avoid underestimating the amount of gas required.
+* `SimulateAndExecute` option to simply simulate the transaction execution without broadcasting.
+* `ChainID` representing which blockchain this transaction pertains to.
+* `Memo` to send with the transaction.
+* `Fees`, the maximum amount the user is willing to pay in fees. Alternative to specifying gas prices.
+* `GasPrices`, the amount per unit of gas the user is willing to pay in fees. Alternative to specifying fees.
 
 The `Context` is initialized using the application's `codec` and data more closely related to the user interaction with the interface, holding data such as the output to the user and the broadcast mode. Read more about `Context` [here](../interfaces/query-lifecycle.md#context).
 
@@ -89,4 +89,4 @@ Since `message`s are module-specific types, each module needs a [`handler`](../b
 
 ## Next {hide}
 
-Learn about the [context](./context.md) {hide}
+Learn about the [context](./context.md) {hide}
diff --git a/docs/ibc/README.md b/docs/ibc/README.md
@@ -0,0 +1,16 @@
+<!--
+order: false
+parent:
+  order: 4
+-->
+
+# IBC
+
+This repository contains reference documentation for the IBC protocol integration and concepts:
+
+1. [Overview](./overview.md)
+2. [Integration](./integration.md)
+3. [Customization](./custom.md)
+
+After reading about IBC, head on to the [Building Modules
+documentation](../building-modules/README.md) to learn more about the process of building modules.