docs: Improve markdownlint configuration (#11104)
## Description Closes: #9404 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
This commit is contained in:
Julien Robert
+2
-2
@@ -23,8 +23,8 @@ module correctly.
|
||||
|
||||
## Pre-requisites Readings
|
||||
|
||||
- [IBC Overview](./overview.md)) {prereq}
|
||||
- [IBC default integration](./integration.md) {prereq}
|
||||
* [IBC Overview](./overview.md)) {prereq}
|
||||
* [IBC default integration](./integration.md) {prereq}
|
||||
|
||||
## Create a custom IBC application module
|
||||
|
||||
|
||||
@@ -14,13 +14,13 @@ send fungible token transfers to other chains.
|
||||
|
||||
Integrating the IBC module to your Cosmos SDK-based application is straighforward. The general changes can be summarized in the following steps:
|
||||
|
||||
- Add required modules to the `module.BasicManager`
|
||||
- Define additional `Keeper` fields for the new modules on the `App` type
|
||||
- Add the module's `StoreKeys` and initialize their `Keepers`
|
||||
- Set up corresponding routers and routes for the `ibc` and `evidence` modules
|
||||
- Add the modules to the module `Manager`
|
||||
- Add modules to `Begin/EndBlockers` and `InitGenesis`
|
||||
- Update the module `SimulationManager` to enable simulations
|
||||
* Add required modules to the `module.BasicManager`
|
||||
* Define additional `Keeper` fields for the new modules on the `App` type
|
||||
* Add the module's `StoreKeys` and initialize their `Keepers`
|
||||
* Set up corresponding routers and routes for the `ibc` and `evidence` modules
|
||||
* Add the modules to the module `Manager`
|
||||
* Add modules to `Begin/EndBlockers` and `InitGenesis`
|
||||
* Update the module `SimulationManager` to enable simulations
|
||||
|
||||
### Module `BasicManager` and `ModuleAccount` permissions
|
||||
|
||||
|
||||
+24
-24
@@ -6,7 +6,7 @@ order: 1
|
||||
|
||||
Learn what IBC is, its components, and use cases. {synopsis}
|
||||
|
||||
## What is the Inter-Blockchain Communication Protocol (IBC)?
|
||||
## What is the Inter-Blockchain Communication Protocol (IBC)
|
||||
|
||||
The Inter-Blockchain Communication protocol (IBC) allows blockchains to talk to each other. The backbone of the Cosmos ecosystem, IBC handles transport across different sovereign blockchains. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains.
|
||||
|
||||
@@ -18,13 +18,13 @@ The abstraction layer details on channels and ports are relevant for app develop
|
||||
|
||||
The following requirements must be met for a module to interact over IBC:
|
||||
|
||||
- Bind to one or more ports
|
||||
* Bind to one or more ports
|
||||
|
||||
- Define the packet data
|
||||
* Define the packet data
|
||||
|
||||
- Define optional acknowledgement structures and methods to encode and decode them
|
||||
* Define optional acknowledgement structures and methods to encode and decode them
|
||||
|
||||
- Implement the IBCModule interface
|
||||
* Implement the IBCModule interface
|
||||
|
||||
## Components Overview
|
||||
|
||||
@@ -34,9 +34,9 @@ This section describes the IBC components and links to the repos.
|
||||
|
||||
IBC clients are light clients that are identified by a unique client id. IBC clients track the consensus states of other blockchains and the proof specs of those blockchains that are required to properly verify proofs against the client's consensus state. A client can be associated with any number of connections to multiple chains. The supported IBC clients are:
|
||||
|
||||
- [Solo Machine light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/06-solomachine): devices such as phones, browsers, or laptops.
|
||||
- [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint): The default for Cosmos SDK-based chains.
|
||||
- [Localhost (loopback) client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/09-localhost): Useful for testing, simulation, and relaying packets to modules on the same application.
|
||||
* [Solo Machine light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/06-solomachine): devices such as phones, browsers, or laptops.
|
||||
* [Tendermint light client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint): The default for Cosmos SDK-based chains.
|
||||
* [Localhost (loopback) client](https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/09-localhost): Useful for testing, simulation, and relaying packets to modules on the same application.
|
||||
|
||||
### [Connections](https://github.com/cosmos/ibc-go/blob/main/modules/core/03-connection)
|
||||
|
||||
@@ -46,13 +46,13 @@ Connections encapsulate two `ConnectionEnd` objects on two separate blockchains.
|
||||
|
||||
In IBC, blockchains do not directly pass messages to each other over the network.
|
||||
|
||||
- To communicate, a blockchain commits some state to a precisely defined path reserved for a specific message type and a specific counterparty. For example, a blockchain that stores a specific connectionEnd as part of a handshake or a packet intended to be relayed to a module on the counterparty chain.
|
||||
* To communicate, a blockchain commits some state to a precisely defined path reserved for a specific message type and a specific counterparty. For example, a blockchain that stores a specific connectionEnd as part of a handshake or a packet intended to be relayed to a module on the counterparty chain.
|
||||
|
||||
- A relayer process monitors for updates to these paths and relays messages by submitting the data stored under the path along with a proof of that data to the counterparty chain.
|
||||
* A relayer process monitors for updates to these paths and relays messages by submitting the data stored under the path along with a proof of that data to the counterparty chain.
|
||||
|
||||
- The paths that all IBC implementations must support for committing IBC messages are defined in [ICS-24 host requirements](https://github.com/cosmos/ics/tree/master/spec/core/ics-024-host-requirements).
|
||||
* The paths that all IBC implementations must support for committing IBC messages are defined in [ICS-24 host requirements](https://github.com/cosmos/ics/tree/master/spec/core/ics-024-host-requirements).
|
||||
|
||||
- The proof format that all implementations must produce and verify is defined in [ICS-23 implementation](https://github.com/confio/ics23).
|
||||
* The proof format that all implementations must produce and verify is defined in [ICS-23 implementation](https://github.com/confio/ics23).
|
||||
|
||||
### [Capabilities](./ocap.md)
|
||||
|
||||
@@ -74,9 +74,9 @@ IBC modules are responsible for claiming the capability that is returned on `Bin
|
||||
|
||||
An IBC channel can be established between two IBC ports. A port is exclusively owned by a single module. IBC packets are sent over channels. Just as IP packets contain the destination IP address, IP port, the source IP address, and source IP port, IBC packets contain the destination portID, channelID, the source portID, and channelID. The IBC packets enable IBC to correctly route the packets to the destination module, while also allowing modules receiving packets to know the sender module.
|
||||
|
||||
- A channel can be `ORDERED` so that packets from a sending module must be processed by the receiving module in the order they were sent.
|
||||
* A channel can be `ORDERED` so that packets from a sending module must be processed by the receiving module in the order they were sent.
|
||||
|
||||
- Recommended, a channel may be `UNORDERED` so that packets from a sending module are processed in the order they arrive, which may not be the order the packets were sent.
|
||||
* Recommended, a channel may be `UNORDERED` so that packets from a sending module are processed in the order they arrive, which may not be the order the packets were sent.
|
||||
|
||||
Modules may choose which channels they wish to communicate over with. IBC expects modules to implement callbacks that are called during the channel handshake. These callbacks may do custom channel initialization logic. If an error is returned, the channel handshake fails. By returning errors on callbacks, modules can programmatically reject and accept channels.
|
||||
|
||||
@@ -95,19 +95,19 @@ Just as ports came with dynamic capabilities, channel initialization returns a d
|
||||
|
||||
Modules communicate with each other by sending packets over IBC channels. All IBC packets contain:
|
||||
|
||||
- Destination `portID`
|
||||
* Destination `portID`
|
||||
|
||||
- Destination `channelID`
|
||||
* Destination `channelID`
|
||||
|
||||
- Source `portID`
|
||||
* Source `portID`
|
||||
|
||||
- Source `channelID`
|
||||
* Source `channelID`
|
||||
|
||||
These port and channels allow the modules to know the sender module of a given packet.
|
||||
|
||||
- A sequence to optionally enforce ordering
|
||||
* A sequence to optionally enforce ordering
|
||||
|
||||
- `TimeoutTimestamp` and `TimeoutHeight`
|
||||
* `TimeoutTimestamp` and `TimeoutHeight`
|
||||
|
||||
When non-zero, these timeout values determine the deadline before which the receiving module must process a packet.
|
||||
|
||||
@@ -131,9 +131,9 @@ For this reason, most modules that use UNORDERED channels are recommended as the
|
||||
|
||||
Modules also write application-specific acknowledgements when processing a packet. Acknowledgements can be done:
|
||||
|
||||
- Synchronously on `OnRecvPacket` if the module processes packets as soon as they are received from IBC module.
|
||||
* Synchronously on `OnRecvPacket` if the module processes packets as soon as they are received from IBC module.
|
||||
|
||||
- Asynchronously if module processes packets at some later point after receiving the packet.
|
||||
* Asynchronously if module processes packets at some later point after receiving the packet.
|
||||
|
||||
This acknowledgement data is opaque to IBC much like the packet `Data` and is treated by IBC as a simple byte string `[]byte`. The receiver modules must encode their acknowledgement so that the sender module can decode it correctly. How the acknowledgement is encoded should be decided through version negotiation during the channel handshake.
|
||||
|
||||
@@ -147,8 +147,8 @@ After an acknowledgement is received successfully on the original sender the cha
|
||||
|
||||
To learn more about IBC, check out the following specifications:
|
||||
|
||||
- [IBC specs](https://github.com/cosmos/ibc/tree/master/spec)
|
||||
- [IBC protocol on the Cosmos SDK](https://github.com/cosmos/ibc-go/tree/main/docs)
|
||||
* [IBC specs](https://github.com/cosmos/ibc/tree/master/spec)
|
||||
* [IBC protocol on the Cosmos SDK](https://github.com/cosmos/ibc-go/tree/main/docs)
|
||||
|
||||
## Next {hide}
|
||||
|
||||
|
||||
+5
-5
@@ -6,8 +6,8 @@ order: 4
|
||||
|
||||
## Prerequisites Readings
|
||||
|
||||
- [IBC Overview](./overview.md) {prereq}
|
||||
- [Events](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/events.md) {prereq}
|
||||
* [IBC Overview](./overview.md) {prereq}
|
||||
* [Events](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/events.md) {prereq}
|
||||
|
||||
## Events
|
||||
|
||||
@@ -42,6 +42,6 @@ piece of information needed to relay a packet.
|
||||
|
||||
## Example Implementations
|
||||
|
||||
- [Golang Relayer](https://github.com/iqlusioninc/relayer)
|
||||
- [Hermes](https://github.com/informalsystems/ibc-rs/tree/master/relayer)
|
||||
- [Typescript Relayer](https://github.com/confio/ts-relayer)
|
||||
* [Golang Relayer](https://github.com/iqlusioninc/relayer)
|
||||
* [Hermes](https://github.com/informalsystems/ibc-rs/tree/master/relayer)
|
||||
* [Typescript Relayer](https://github.com/confio/ts-relayer)
|
||||
|
||||
@@ -4,7 +4,7 @@ parent:
|
||||
order: 3
|
||||
-->
|
||||
|
||||
### Upgrading IBC Chains Overview
|
||||
# Upgrading IBC Chains Overview
|
||||
|
||||
This directory contains information on how to upgrade an IBC chain without breaking counterparty clients and connections.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Learn how to upgrade your chain and counterparty clients. {synopsis}
|
||||
|
||||
The information in this doc for upgrading chains is relevant to Cosmos SDK chains. However, the guide for counterparty clients is relevant to any Tendermint client that enables upgrades.
|
||||
|
||||
### IBC Client Breaking Upgrades
|
||||
## IBC Client Breaking Upgrades
|
||||
|
||||
IBC-connected chains must perform an IBC upgrade if their upgrade will break counterparty IBC clients. The current IBC protocol supports upgrading tendermint chains for a specific subset of IBC-client-breaking upgrades. Here is the exhaustive list of IBC client-breaking upgrades and whether the IBC protocol currently supports such upgrades.
|
||||
|
||||
@@ -26,7 +26,7 @@ Note: Since upgrades are only implemented for Tendermint clients, this doc only
|
||||
8. Upgrading to a non-backwards compatible version of IBC: **Unsupported**, as IBC version is negotiated on connection handshake.
|
||||
9. Changing the Tendermint LightClient algorithm: **Partially Supported**. Changes to the light client algorithm that do not change the ClientState or ConsensusState struct may be supported, provided that the counterparty is also upgraded to support the new light client algorithm. Changes that require updating the ClientState and ConsensusState structs themselves are theoretically possible by providing a path to translate an older ClientState struct into the new ClientState struct; however this is not currently implemented.
|
||||
|
||||
### Step-by-Step Upgrade Process for Cosmos SDK chains
|
||||
## Step-by-Step Upgrade Process for Cosmos SDK chains
|
||||
|
||||
If the IBC-connected chain is conducting an upgrade that will break counterparty clients, it must ensure that the upgrade is first supported by IBC using the list above and then execute the upgrade process described below in order to prevent counterparty clients from breaking.
|
||||
|
||||
@@ -37,7 +37,7 @@ Upon the `UpgradeProposal` passing, the upgrade module will commit the UpgradedC
|
||||
|
||||
Once the chain reaches the upgrade height and halts, a relayer can upgrade the counterparty clients to the last block of the old chain. They can then submit the proofs of the `UpgradedClient` and `UpgradedConsensusState` against this last block and upgrade the counterparty client.
|
||||
|
||||
### Step-by-Step Upgrade Process for Relayers Upgrading Counterparty Clients
|
||||
## Step-by-Step Upgrade Process for Relayers Upgrading Counterparty Clients
|
||||
|
||||
Once the upgrading chain has committed to upgrading, relayers must wait till the chain halts at the upgrade height before upgrading counterparty clients. This is because chains may reschedule or cancel upgrade plans before they occur. Thus, relayers must wait till the chain reaches the upgrade height and halts before they can be sure the upgrade will take place.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user