Skip to content

Commit

Permalink
docspelling and grammar (#6480)
Browse files Browse the repository at this point in the history
Minimal changes
  • Loading branch information
okwme committed Jun 22, 2020
1 parent 4b0c669 commit 6700d77
Showing 1 changed file with 5 additions and 5 deletions.
10 changes: 5 additions & 5 deletions docs/core/ibc.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ To have your module interact over IBC you must: bind to a port(s), define your o

**[Clients](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/02-client)**: IBC Clients are light clients (identified by a unique client-id) that track the consensus states of other blockchains, along with the proof spec necessary to properly verify proofs against the client's consensus state. A client may be associated with any number of connections.

**[Connections](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/03-connection)**: Connections encapsulate two `ConnectionEnd` objects on two seperate blockchains. Each `ConnectionEnd` is associated with a client of the other blockchain (ie counterparty blockchain). The connection handshake is responsible for verifying that the light clients on each chain are correct for their respective counterparties. Connections, once established, are responsible for facilitation all cross-chain verification of IBC state. A connection may be associated with any number of channels.
**[Connections](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/03-connection)**: Connections encapsulate two `ConnectionEnd` objects on two seperate blockchains. Each `ConnectionEnd` is associated with a client of the other blockchain (ie counterparty blockchain). The connection handshake is responsible for verifying that the light clients on each chain are correct for their respective counterparties. Connections, once established, are responsible for facilitating all cross-chain verification of IBC state. A connection may be associated with any number of channels.

**[Proofs](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/23-commitment) and [Paths](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/24-host)**: In IBC, blockchains do not directly pass messages to each other over the network. Instead, to communicate, a blockchain will commit some state to a specifically defined path reserved for a specific message type and a specific counterparty (perhaps storing 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 will relay messages, by submitting the data stored under the path along with a proof to the counterparty chain. The paths that all IBC implementations must use for committing IBC messages is defined in [ICS-24](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements) and the proof format that all implementations must be able to produce and verify is defined in this [ICS-23 implementation](https://github.com/confio/ics23).

**[Capabilities](https://github.com/cosmos/cosmos-sdk/tree/master/x/capability)**: IBC is intended to work in execution environements where modules do not necessarily trust each other. Thus IBC must authenticate module actions on ports and channels so that only modules with the appropriate permissions can use them. This is accomplished using dynamic capabilities ([ADR](../architecture/adr-003-dynamic-capability-store.md)). Upon binding to a port or creating a channel for a module, IBC will return a dynamic capability that the module must claim in order to use that port or channel. This prevents other modules from using that port or channel since they will not own the appropriate capability. For information on the object capability model, look [here](./ocap.md)

### Channels and Ports

While the above is useful background information, IBC modules do not need to interact at all with these lower-level abstractions. The relevant abstraction layer for IBC application developers is that of channels and ports. IBC applications should be written as self-contained **modules**. A module on one blockchain can thus communicate with other modules on other blockchains by sending, receiving and acknowledging packets through channels, which are uniquely identified by the `(channelID, portID)` tuple. A useful analogy is to consider IBC modules as internet applications on a computer. A channel can then be conceptualized as an IP connection, with the IBC portID being analogous to a IP port and the IBC channelID being analogous to an IP address. Thus, a single instance of an IBC module may communicate on the same port with any number of other modules and and IBC will correctly route all packets to the relevant module using the (channelID, portID tuple). An IBC module may also communicate with another IBC module over multiple ports, with each `(portID<->portID)` packet stream being sent on a different unique channel.
While the above is useful background information, IBC modules do not need to interact at all with these lower-level abstractions. The relevant abstraction layer for IBC application developers is that of channels and ports. IBC applications should be written as self-contained **modules**. A module on one blockchain can thus communicate with other modules on other blockchains by sending, receiving and acknowledging packets through channels, which are uniquely identified by the `(channelID, portID)` tuple. A useful analogy is to consider IBC modules as internet applications on a computer. A channel can then be conceptualized as an IP connection, with the IBC portID being analogous to a IP port and the IBC channelID being analogous to an IP address. Thus, a single instance of an IBC module may communicate on the same port with any number of other modules and IBC will correctly route all packets to the relevant module using the `(channelID, portID)` tuple. An IBC module may also communicate with another IBC module over multiple ports, with each `(portID<->portID)` packet stream being sent on a different unique channel.

#### [Ports](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/05-port)

Expand Down Expand Up @@ -55,7 +55,7 @@ func InitGenesis(ctx sdk.Context, keeper keeper.Keeper, state types.GenesisState

#### [Channels](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc/04-channel)

An IBC channel can be established between 2 IBC ports. Currently, a port is exclusively owned by a single module. IBC packets are sent over channels. Just as IP packets contain the destination IP address and IP port as well as the the source IP address and source IP port, IBC packets will contain the destination portID and channelID as well as the source portID and channelID. This enables IBC to correctly route packets to the destination module, while also allowing modules receiving packets to know the sender module.
An IBC channel can be established between 2 IBC ports. Currently, a port is exclusively owned by a single module. IBC packets are sent over channels. Just as IP packets contain the destination IP address and IP port as well as the source IP address and source IP port, IBC packets will contain the destination portID and channelID as well as the source portID and channelID. This enables IBC to correctly route packets to the destination module, while also allowing modules receiving packets to know the sender module.

A channel may be `ORDERED`, in which case, packets from a sending module must be processed by the receiving module in the order they were sent. Or a channel may be `UNORDERED`, in which case packets from a sending module are processed in the order they arrive (may not be the order they were sent).

Expand Down Expand Up @@ -180,7 +180,7 @@ Modules send custom application data to each other inside the `Data []byte` fiel

Thus, modules connected by a channel must agree on what application data they are sending over the channel, as well as how they will encode/decode it. This process is not specified by IBC as it is up to each application module to determine how to implement this agreement. However, for most applications this will happen as a version negotiation during the channel handshake. While more complex version negotiation is possible to implement inside the channel opening handshake, a very simple version negotation is implemented in the [ibc-transfer module](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc-transfer/module.go).

Thus a module must define its a custom packet data structure, along with a well-defined way to encode and decode it to and from `[]byte`.
Thus a module must define a custom packet data structure, along with a well-defined way to encode and decode it to and from `[]byte`.

```go
// Custom packet data defined in application module
Expand Down Expand Up @@ -276,7 +276,7 @@ OnRecvPacket(
::: warning
`OnRecvPacket` should **only** return an error if we want the entire receive packet execution (including the IBC handling) to be reverted. This will allow the packet to be replayed in the case that some mistake in the relaying caused the packet processing to fail.

If there was some application-level error happened while processing the packet data, in most cases, we will not want the packet processing to revert. Instead, we may want to encode this failure into the acknowledgement and finish processing the packet. This will ensure the packet cannot be replayed, and will also allow the sender module to potentially remediate the situation upon receiving the acknowledgement. An example of this technique is in the ibc-transfer module's [OnRecvPacket](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc-transfer/module.go).
If some application-level error happened while processing the packet data, in most cases, we will not want the packet processing to revert. Instead, we may want to encode this failure into the acknowledgement and finish processing the packet. This will ensure the packet cannot be replayed, and will also allow the sender module to potentially remediate the situation upon receiving the acknowledgement. An example of this technique is in the ibc-transfer module's [OnRecvPacket](https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc-transfer/module.go).
:::

**Acknowledging Packets**: If the receiving module writes an ackowledgement while processing the packet, a relayer can relay back the acknowledgement to the sender module. The sender module can then process the acknowledgement using the `OnAcknowledgementPacket` callback. The contents of the acknowledgement is entirely upto the modules on the channel (just like the packet data); however, it may often contain information on whether the packet was successfully received and processed along with some additional data that could be useful for remediation if the packet processing failed.
Expand Down

0 comments on commit 6700d77

Please sign in to comment.