Thomas/1584 update docs apps (backport #1675)

docs/ibc/apps/apps.md

@@ -0,0 +1,51 @@
+<!--
+order: 1
+-->
+
+# IBC Applications
+
+Learn how to build custom IBC application modules that enable packets to be sent to and received from other IBC-enabled chains. {synopsis}
+
+This document serves as a guide for developers who want to write their own Inter-blockchain Communication Protocol (IBC) applications for custom use cases.
+
+Due to the modular design of the IBC protocol, IBC application developers do not need to concern themselves with the low-level details of clients, connections, and proof verification. Nevertheless, an overview of these low-level concepts can be found in [the Overview section](../overview.md).
+The document goes into detail on the abstraction layer most relevant for application developers (channels and ports), and describes how to define your own custom packets, `IBCModule` callbacks and more to make an application module IBC ready.
+
+**To have your module interact over IBC you must:**
+
+- implement the `IBCModule` interface, i.e.:
+  - channel (opening) handshake callbacks
+  - channel closing handshake callbacks
+  - packet callbacks
+- bind to a port(s)
+- add keeper methods
+- define your own packet data and acknowledgement structs as well as how to encode/decode them
+- add a route to the IBC router
+
+The following sections provide a more detailed explanation of how to write an IBC application
+module correctly corresponding to the listed steps.
+
+## Pre-requisites Readings
+
+- [IBC Overview](../overview.md)) {prereq}
+- [IBC default integration](../integration.md) {prereq}
+
+## Working example
+
+For a real working example of an IBC application, you can look through the `ibc-transfer` module
+which implements everything discussed in this section.
+
+Here are the useful parts of the module to look at:
+
+[Binding to transfer
+port](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/keeper/genesis.go)
+
+[Sending transfer
+packets](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/keeper/relay.go)
+
+[Implementing IBC
+callbacks](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/ibc_module.go)
+
+## Next {hide}
+
+Learn about [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/intro.md) {hide}

docs/ibc/apps/bindports.md

@@ -0,0 +1,114 @@
+<!--
+order: 3
+-->
+
+# Bind ports
+
+Learn what changes to make to bind modules to their ports on initialization. {synopsis}
+
+## Pre-requisites Readings
+
+- [IBC Overview](../overview.md)) {prereq}
+- [IBC default integration](../integration.md) {prereq}
+
+Currently, ports must be bound on app initialization. In order to bind modules to their respective ports on initialization, the following needs to be implemented:
+
+> Note that `portID` does not refer to a certain numerical ID, like `localhost:8080` with a `portID` 8080. Rather it refers to the application module the port binds. For IBC Modules built with the Cosmos SDK, it defaults to the module's name and for Cosmwasm contracts it defaults to the contract address.
+
+1. Add port ID to the `GenesisState` proto definition:
+
+   ```protobuf
+   message GenesisState {
+        string port_id = 1;
+        // other fields
+   }
+   ```
+
+1. Add port ID as a key to the module store:
+
+   ```go
+   // x/<moduleName>/types/keys.go
+   const (
+       // ModuleName defines the IBC Module name
+       ModuleName = "moduleName"
+
+       // Version defines the current version the IBC
+       // module supports
+       Version = "moduleVersion-1"
+
+       // PortID is the default port id that module binds to
+       PortID = "portID"
+
+       // ...
+   )
+   ```
+
+1. Add port ID to `x/<moduleName>/types/genesis.go`:
+
+   ```go
+   // in x/<moduleName>/types/genesis.go
+
+   // DefaultGenesisState returns a GenesisState with "transfer" as the default PortID.
+   func DefaultGenesisState() *GenesisState {
+       return &GenesisState{
+           PortId:      PortID,
+           // additional k-v fields
+       }
+   }
+
+   // Validate performs basic genesis state validation returning an error upon any
+   // failure.
+   func (gs GenesisState) Validate() error {
+       if err := host.PortIdentifierValidator(gs.PortId); err != nil {
+           return err
+       }
+       //addtional validations
+
+       return gs.Params.Validate()
+   }
+   ```
+
+1. Bind to port(s) in the module keeper's `InitGenesis`:
+
+   ```go
+   // InitGenesis initializes the ibc-module state and binds to PortID.
+   func (k Keeper) InitGenesis(ctx sdk.Context, state types.GenesisState) {
+       k.SetPort(ctx, state.PortId)
+
+       // ...
+
+       // Only try to bind to port if it is not already bound, since we may already own
+       // port capability from capability InitGenesis
+       if !k.IsBound(ctx, state.PortId) {
+           // transfer module binds to the transfer port on InitChain
+           // and claims the returned capability
+           err := k.BindPort(ctx, state.PortId)
+           if err != nil {
+               panic(fmt.Sprintf("could not claim port capability: %v", err))
+           }
+       }
+
+       // ...
+   }
+   ```
+
+   With:
+
+   ```go
+   // IsBound checks if the  module is already bound to the desired port
+   func (k Keeper) IsBound(ctx sdk.Context, portID string) bool {
+       _, ok := k.scopedKeeper.GetCapability(ctx, host.PortPath(portID))
+       return ok
+   }
+
+   // BindPort defines a wrapper function for the port Keeper's function in
+   // order to expose it to module's InitGenesis function
+   func (k Keeper) BindPort(ctx sdk.Context, portID string) error {
+       cap := k.portKeeper.BindPort(ctx, portID)
+       return k.ClaimCapability(ctx, cap, host.PortPath(portID))
+   }
+   ```
+
+   The module binds to the desired port(s) and returns the capabilities.
+
+   In the above we find reference to keeper methods that wrap other keeper functionality, in the next section the keeper methods that need to be implemented will be defined.