docs: begin removal of internal "spec" directories (#634)

* begin removal of spec docs within core ibc * remove broken link * Apply suggestions from code review Co-authored-by: Damian Nolan <damiannolan@gmail.com> * remove broken link * remove broken links * Apply suggestions from code review Co-authored-by: Carlos Rodriguez <crodveg@yahoo.es> Co-authored-by: Damian Nolan <damiannolan@gmail.com> Co-authored-by: Carlos Rodriguez <crodveg@yahoo.es>
cosmos · Dec 22, 2021 · b7fb4f1 · b7fb4f1
1 parent ce4c81e
commit b7fb4f1
Show file tree

Hide file tree

Showing 14 changed files with 101 additions and 947 deletions.
diff --git a/modules/core/spec/06_events.md → docs/ibc/events.md b/modules/core/spec/06_events.md → docs/ibc/events.md
@@ -1,9 +1,11 @@
 <!--
-order: 6
+order: 5
 -->
 
 # Events
 
+**NOTE**: This document is unmaintained and may be out of date!
+
 The IBC module emits the following events. It can be expected that the type `message`,
 with an attirbute key of `action` will represent the first event for each message
 being processed as emitted by the SDK's baseapp. Each IBC TAO message will

diff --git a/docs/ibc/overview.md b/docs/ibc/overview.md
@@ -37,10 +37,19 @@ Read on for a detailed explanation of how to write a self-contained IBC applicat
 
 ### [Clients](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client)
 
-IBC clients are light clients that are identified by a unique client-id. IBC clients 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 can be associated with any number of connections to the counterparty
-chain. 
+IBC clients are on-chain light clients. Each light client is identified by a unique client-id. 
+IBC clients 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 can be associated with any number 
+of connections to the counterparty chain. The client identifier is auto generated using the client type 
+and the global client counter appended in the format: `{client-type}-{N}`. 
+
+A `ClientState` should contain chain specific and light client specific information necessary for verifying updates
+and upgrades to the IBC client. The `ClientState` may contain information such as chain-id, latest height, proof specs, 
+unbonding periods or the status of the light client. The `ClientState` should not contain information that
+is specific to a given block at a certain height, this is the function of the `CosnensusState`. Each `ConsensusState`
+should be associated with a unique block and should be referenced using a height. IBC clients are given a 
+client identifier prefixed store to store their associated client state and consensus states along with 
+any metadata associated with the consensus states. Consensus states are stored using their associated height. 
 
 The supported IBC clients are:
 
@@ -49,6 +58,60 @@ The supported IBC clients are:
 * [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.
 
+### IBC Client Heights
+
+IBC Client Heights are represented by the struct:
+
+```go
+type Height struct {
+   RevisionNumber uint64
+   RevisionHeight uint64
+}
+```
+
+The `RevisionNumber` represents the revision of the chain that the height is representing.
+A revision typically represents a continuous, monotonically increasing range of block-heights.
+The `RevisionHeight` represents the height of the chain within the given revision.
+
+On any reset of the `RevisionHeight`—for example, when hard-forking a Tendermint chain—
+the `RevisionNumber` will get incremented. This allows IBC clients to distinguish between a
+block-height `n` of a previous revision of the chain (at revision `p`) and block-height `n` of the current
+revision of the chain (at revision `e`).
+
+`Height`s that share the same revision number can be compared by simply comparing their respective `RevisionHeight`s.
+`Height`s that do not share the same revision number will only be compared using their respective `RevisionNumber`s.
+Thus a height `h` with revision number `e+1` will always be greater than a height `g` with revision number `e`,
+**REGARDLESS** of the difference in revision heights.
+
+Ex:
+
+```go
+Height{RevisionNumber: 3, RevisionHeight: 0} > Height{RevisionNumber: 2, RevisionHeight: 100000000000}
+```
+
+When a Tendermint chain is running a particular revision, relayers can simply submit headers and proofs with the revision number
+given by the chain's `chainID`, and the revision height given by the Tendermint block height. When a chain updates using a hard-fork 
+and resets its block-height, it is responsible for updating its `chainID` to increment the revision number.
+IBC Tendermint clients then verifies the revision number against their `chainID` and treat the `RevisionHeight` as the Tendermint block-height.
+
+Tendermint chains wishing to use revisions to maintain persistent IBC connections even across height-resetting upgrades must format their `chainID`s
+in the following manner: `{chainID}-{revision_number}`. On any height-resetting upgrade, the `chainID` **MUST** be updated with a higher revision number
+than the previous value.
+
+Ex:
+
+- Before upgrade `chainID`: `gaiamainnet-3`
+- After upgrade `chainID`: `gaiamainnet-4`
+
+Clients that do not require revisions, such as the solo-machine client, simply hardcode `0` into the revision number whenever they
+need to return an IBC height when implementing IBC interfaces and use the `RevisionHeight` exclusively.
+
+Other client-types can implement their own logic to verify the IBC heights that relayers provide in their `Update`, `Misbehavior`, and
+`Verify` functions respectively.
+
+The IBC interfaces expect an `ibcexported.Height` interface, however all clients must use the concrete implementation provided in
+`02-client/types` and reproduced above.
+
 ### [Connections](https://github.com/cosmos/ibc-go/blob/main/modules/core/03-connection)
 
 Connections encapsulate two `ConnectionEnd` objects on two separate blockchains. Each
@@ -67,6 +130,8 @@ of a handshake or a packet intended to be relayed to a module on the counterpart
 process monitors for updates to these paths and relays messages by submitting the data stored
 under the path and a proof to the counterparty chain. 
 
+Proofs are passed from core IBC to light-clients as bytes. It is up to light client implementation to interpret these bytes appropriately.
+
 - The paths that all IBC implementations must use for committing IBC messages is defined in
 [ICS-24 Host State Machine Requirements](https://github.com/cosmos/ics/tree/master/spec/core/ics-024-host-requirements). 
 - The proof format that all implementations must be able to produce and verify is defined in [ICS-23 Proofs](https://github.com/confio/ics23) implementation.
@@ -138,11 +203,27 @@ If all handshake steps are successful, the channel is opened on both sides. At e
 associated with the `ChannelEnd` executes its callback. So
 on `ChanOpenInit`, the module on chain A executes its callback `OnChanOpenInit`.
 
+The channel identifier is auto derived in the format: `channel-{N}` where N is the next sequence to be used. 
+
 Just as ports came with dynamic capabilities, channel initialization returns a dynamic capability
 that the module **must** claim so that they can pass in a capability to authenticate channel actions
 like sending packets. The channel capability is passed into the callback on the first parts of the
 handshake; either `OnChanOpenInit` on the initializing chain or `OnChanOpenTry` on the other chain.
 
+#### Closing channels
+
+Closing a channel occurs in 2 handshake steps as defined in [ICS 04](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics).
+
+`ChanCloseInit` closes a channel on the executing chain if the channel exists, it is not 
+already closed and the connection it exists upon is OPEN. Channels can only be closed by a 
+calling module or in the case of a packet timeout on an ORDERED channel.
+
+`ChanCloseConfirm` is a response to a counterparty channel executing `ChanCloseInit`. The channel
+on the executing chain closes if the channel exists, the channel is not already closed, 
+the connection the channel exists upon is OPEN and the executing chain successfully verifies
+that the counterparty channel has been closed.
+
+
 ### [Packets](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel)
 
 Modules communicate with each other by sending packets over IBC channels. All
@@ -211,7 +292,6 @@ The original sender module then executes application-specific acknowledgment log
 If you want to learn more about IBC, check the following specifications:
 
 * [IBC specification overview](https://github.com/cosmos/ibc/blob/master/README.md)
-* [IBC SDK specification](../../modules/core/spec/README.md)
 
 ## Next {hide}
 

diff --git a/modules/core/spec/07_params.md → docs/ibc/params.md b/modules/core/spec/07_params.md → docs/ibc/params.md
@@ -1,12 +1,12 @@
 <!--
-order: 7
+order: 4
 -->
 
 # Parameters
 
-## Clients
+## 02-Client
 
-The ibc clients contain the following parameters:
+The 02-client submodule contains the following parameters:
 
 | Key              | Type | Default Value |
 |------------------|------|---------------|

diff --git a/docs/ibc/relayer.md b/docs/ibc/relayer.md
@@ -1,5 +1,5 @@
 <!--
-order: 4
+order: 6
 -->
 
 # Relayer

diff --git a/modules/core/24-host/doc.go b/modules/core/24-host/doc.go
@@ -0,0 +1,9 @@
+/*
+24-host is an implementation of ICS24.
+
+The storage path supported are defined in [ICS24](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements#path-space).
+
+Hostname validation is implemented as defined in [ICS 24](https://github.com/cosmos/ibc/tree/master/spec/core/ics-024-host-requirements).
+
+*/
+package host