update fee mw docs, add formating, fix typos, increase readability (cosmos#1665) (cosmos#1750)

* update fee mw docs, add formating, fix typos, increase readability

* fix broken link

* Apply suggestions from code review

(De)capitalize headings and references to headings for consistency

Co-authored-by: Carlos Rodriguez <[email protected]>

* resolving merge conflict

* split the CLI commands and small typo correction

Co-authored-by: Carlos Rodriguez <[email protected]>
(cherry picked from commit aaccbd1)

Co-authored-by: tmsdkeys <[email protected]>

Author: 2 people

docs/.vuepress/config.js

@@ -267,11 +267,6 @@ module.exports = {
                   directory: false,
                   path: "/middleware/ics29-fee/integration.html",
                 },
-                {
-                  title: "End Users",
-                  directory: false,
-                  path: "/middleware/ics29-fee/end-users.html",
-                },
                 {
                   title: "Fee Messages",
                   directory: false,
@@ -287,6 +282,11 @@ module.exports = {
                   directory: false,
                   path: "/middleware/ics29-fee/events.html",
                 },
+                {
+                  title: "End Users",
+                  directory: false,
+                  path: "/middleware/ics29-fee/end-users.html",
+                },
               ],
             },
           ],

docs/assets/fee-mw/feeflow.png

@@ -8,7 +8,7 @@ Learn how to incentivize IBC packets using the ICS29 Fee Middleware module. {syn
 
 ## Pre-requisite readings
 
-* [Fee Middleware](overview.md) {prereq}
+- [Fee Middleware](overview.md) {prereq}
 
 ## Summary
 
@@ -17,7 +17,6 @@ Different types of end users:
 - CLI users who want to manually incentivize IBC packets
 - Client developers
 
-
 The Fee Middleware module allows end users to add a 'tip' to each IBC packet which will incentivize relayer operators to relay packets between chains. gRPC endpoints are exposed for client developers as well as a simple CLI for manually incentivizing IBC packets.
 
 ## CLI Users
@@ -26,6 +25,6 @@ For an in depth guide on how to use the ICS29 Fee Middleware module using the CL
 
 ## Client developers
 
-Client developers can read more about the relevant ICS29 message types in the [Escrowing and paying out fees section](../ics29-fee/msgs.md).
+Client developers can read more about the relevant ICS29 message types in the [Fee messages section](../ics29-fee/msgs.md).
 
 [CosmJS](https://github.com/cosmos/cosmjs) is a useful client library for signing and broadcasting Cosmos SDK messages.

docs/assets/fee-mw/msgpaypacket.png

@@ -4,10 +4,12 @@ order: 5
 
 # Events
 
+An overview of all events related to ICS-29 {synopsis}
+
 ## `MsgPayPacketFee`, `MsgPayPacketFeeAsync`
 
 | Type                    | Attribute Key   | Attribute Value |
-|-------------------------|-----------------|-----------------|
+| ----------------------- | --------------- | --------------- |
 | incentivized_ibc_packet | port_id         | {portID}        |
 | incentivized_ibc_packet | channel_id      | {channelID}     |
 | incentivized_ibc_packet | packet_sequence | {sequence}      |
@@ -19,16 +21,16 @@ order: 5
 ## `RegisterPayee`
 
 | Type           | Attribute Key | Attribute Value |
-|----------------|------------|--------------------|
-| register_payee | relayer    | {relayer}          |
-| register_payee | payee      | {payee}            |
-| register_payee | channel_id | {channelID}        |
-| message        | module     | fee-ibc            |
+| -------------- | ------------- | --------------- |
+| register_payee | relayer       | {relayer}       |
+| register_payee | payee         | {payee}         |
+| register_payee | channel_id    | {channelID}     |
+| message        | module        | fee-ibc         |
 
 ## `RegisterCounterpartyPayee`
 
 | Type                        | Attribute Key      | Attribute Value     |
-|-----------------------------|--------------------|---------------------|
+| --------------------------- | ------------------ | ------------------- |
 | register_counterparty_payee | relayer            | {relayer}           |
 | register_counterparty_payee | counterparty_payee | {counterpartyPayee} |
 | register_counterparty_payee | channel_id         | {channelID}         |

docs/assets/fee-mw/paypacketfeeasync.png

@@ -8,26 +8,30 @@ Learn about payee registration for the distribution of packet fees. The followin
 
 ## Pre-requisite readings
 
-* [Fee Middleware](overview.md) {prereq}
+- [Fee Middleware](overview.md) {prereq}
 
 Packet fees are divided into 3 distinct amounts in order to compensate relayer operators for packet relaying on fee enabled IBC channels.
 
 - `RecvFee`: The sum of all packet receive fees distributed to a payee for successful execution of `MsgRecvPacket`.
 - `AckFee`: The sum of all packet acknowledgement fees distributed to a payee for successful execution of `MsgAcknowledgement`.
 - `TimeoutFee`: The sum of all packet timeout fees distributed to a payee for successful execution of `MsgTimeout`.
 
-## Register a payee address for forward relaying
+## Register a counterparty payee address for forward relaying
+
+As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the forward relayer describes the actor who performs the submission of `MsgRecvPacket` on the destination chain.
+Fee distribution for incentivized packet relays takes place on the packet source chain.
+
+> Relayer operators are expected to register a counterparty payee address, in order to be compensated accordingly with `RecvFee`s upon completion of a packet lifecycle.
 
-As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the forward relayer describes the actor who performs the submission of `MsgRecvPacket` on the destination chain. 
-Fee distribution for incentivized packet relays takes place on the packet source chain. 
-Relayer operators are expected to register a counterparty payee address, in order to be compensated accordingly with `RecvFee`s upon completion of a packet lifecycle. 
 The counterparty payee address registered on the destination chain is encoded into the packet acknowledgement and communicated as such to the source chain for fee distribution.
-If a counterparty payee is not registered for the forward relayer on the destination chain, the escrowed fees will be refunded upon fee distribution.
+**If a counterparty payee is not registered for the forward relayer on the destination chain, the escrowed fees will be refunded upon fee distribution.**
+
+### Relayer operator actions?
 
-A transaction must be submitted to the destination chain including a `CounterpartyPayee` address of an account on the source chain.
+A transaction must be submitted **to the destination chain** including a `CounterpartyPayee` address of an account on the source chain.
 The transaction must be signed by the `Relayer`.
 
-Note: If a module account address is used as the `CounterpartyPayee` it is recommended to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module. 
+Note: If a module account address is used as the `CounterpartyPayee` it is recommended to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module.
 
 ```go
 type MsgRegisterCounterpartyPayee struct {
@@ -42,27 +46,34 @@ type MsgRegisterCounterpartyPayee struct {
 }
 ```
 
-This message is expected to fail if:
-
-- `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators).
-- `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)).
-- `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
-- `CounterpartyPayee` is empty.
+> This message is expected to fail if:
+>
+> - `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators).
+> - `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)).
+> - `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
+> - `CounterpartyPayee` is empty.
 
 See below for an example CLI command:
 
-```
-simd tx ibc-fee register-counterparty-payee transfer channel-0 cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh osmo1v5y0tz01llxzf4c2afml8s3awue0ymju22wxx2 --from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh
+```bash
+simd tx ibc-fee register-counterparty-payee transfer channel-0 \
+cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh \
+osmo1v5y0tz01llxzf4c2afml8s3awue0ymju22wxx2 \
+--from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh
 ```
 
-## Register a payee address for reverse and timeout relaying
+## Register an alternative payee address for reverse and timeout relaying
 
-As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the reverse relayer describes the actor who performs the submission of `MsgAcknowledgement` on the source chain. 
+As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the reverse relayer describes the actor who performs the submission of `MsgAcknowledgement` on the source chain.
 Similarly the timeout relayer describes the actor who performs the submission of `MsgTimeout` (or `MsgTimeoutOnClose`) on the source chain.
-Relayer operators may choose to register an optional payee address, in order to be compensated accordingly with `AckFee`s and `TimeoutFee`s upon completion of a packet life cycle.
+
+> Relayer operators **may choose** to register an optional payee address, in order to be compensated accordingly with `AckFee`s and `TimeoutFee`s upon completion of a packet life cycle.
+
 If a payee is not registered for the reverse or timeout relayer on the source chain, then fee distribution assumes the default behaviour, where fees are paid out to the relayer account which delivers `MsgAcknowledgement` or `MsgTimeout`/`MsgTimeoutOnClose`.
 
-A transaction must be submitted to the source chain including a `Payee` address of an account on the source chain.
+### Relayer operator actions
+
+A transaction must be submitted **to the source chain** including a `Payee` address of an account on the source chain.
 The transaction must be signed by the `Relayer`.
 
 Note: If a module account address is used as the `Payee` it is recommended to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module.
@@ -80,15 +91,18 @@ type MsgRegisterPayee struct {
 }
 ```
 
-This message is expected to fail if:
-
-- `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators).
-- `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)).
-- `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
-- `Payee` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
+> This message is expected to fail if:
+>
+> - `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators).
+> - `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)).
+> - `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
+> - `Payee` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)).
 
 See below for an example CLI command:
 
-```
-simd tx ibc-fee register-payee transfer channel-0 cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh cosmos153lf4zntqt33a4v0sm5cytrxyqn78q7kz8j8x5 --from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh
+```bash
+simd tx ibc-fee register-payee transfer channel-0 \
+cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh \
+cosmos153lf4zntqt33a4v0sm5cytrxyqn78q7kz8j8x5 \
+--from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh
 ```