From 7b599cb6381340f442678d96cd966de26485147a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Colin=20Axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Wed, 15 Dec 2021 12:54:12 +0100 Subject: [PATCH 1/6] begin removal of spec docs within core ibc --- .../spec/06_events.md => docs/ibc/events.md | 4 +- docs/ibc/overview.md | 89 +++- .../spec/07_params.md => docs/ibc/params.md | 6 +- docs/ibc/relayer.md | 2 +- modules/core/24-host/doc.go | 9 + modules/core/spec/01_concepts.md | 188 ------- modules/core/spec/02_state.md | 28 - modules/core/spec/03_state_transitions.md | 106 ---- modules/core/spec/04_messages.md | 497 ------------------ modules/core/spec/05_callbacks.md | 80 --- modules/core/spec/README.md | 26 - 11 files changed, 101 insertions(+), 934 deletions(-) rename modules/core/spec/06_events.md => docs/ibc/events.md (99%) rename modules/core/spec/07_params.md => docs/ibc/params.md (88%) create mode 100644 modules/core/24-host/doc.go delete mode 100644 modules/core/spec/02_state.md delete mode 100644 modules/core/spec/03_state_transitions.md delete mode 100644 modules/core/spec/04_messages.md delete mode 100644 modules/core/spec/05_callbacks.md delete mode 100644 modules/core/spec/README.md diff --git a/modules/core/spec/06_events.md b/docs/ibc/events.md similarity index 99% rename from modules/core/spec/06_events.md rename to docs/ibc/events.md index 8a416217e1f..b7b28351cab 100644 --- a/modules/core/spec/06_events.md +++ b/docs/ibc/events.md @@ -1,9 +1,11 @@ # 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 index 563a56167ad..47cca84b510 100644 --- 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. +An 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`). + +`Heights` that share the same revision number can be compared by simply comparing their respective `RevisionHeights`. +Heights that do not share the same revision number will only be compared using their respective `RevisionNumbers`. +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 chain-id 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 chain-ids +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 may 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 should 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 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` will close 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 will be closed 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 diff --git a/modules/core/spec/07_params.md b/docs/ibc/params.md similarity index 88% rename from modules/core/spec/07_params.md rename to docs/ibc/params.md index 67e79ef81dd..3040eea50b7 100644 --- a/modules/core/spec/07_params.md +++ b/docs/ibc/params.md @@ -1,12 +1,12 @@ # 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 index 29699d7cb3c..c839c14b60f 100644 --- a/docs/ibc/relayer.md +++ b/docs/ibc/relayer.md @@ -1,5 +1,5 @@ # Relayer diff --git a/modules/core/24-host/doc.go b/modules/core/24-host/doc.go new file mode 100644 index 00000000000..0d73c4e7efe --- /dev/null +++ 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 diff --git a/modules/core/spec/01_concepts.md b/modules/core/spec/01_concepts.md index 05c4e8a3104..0ab6fa70710 100644 --- a/modules/core/spec/01_concepts.md +++ b/modules/core/spec/01_concepts.md @@ -4,28 +4,6 @@ order: 1 # Concepts -## Client Creation, Updates, and Upgrades - -IBC clients are on chain light clients. The light client is responsible for verifying -counterparty state. A light client can be created by any user submitting a valid initial -`ClientState` and `ConsensusState`. The client identifier is auto generated using the -client type and the global client counter appended in the format: `{client-type}-{N}`. -Clients are given a client identifier prefixed store to store their associated client -state and consensus states. Consensus states are stored using their associated height. - -Clients can be updated by any user submitting a valid `Header`. The client state callback -to `CheckHeaderAndUpdateState` is responsible for verifying the header against previously -stored state. The function should also return the updated client state and consensus state -if the header is considered a valid update. A light client, such as Tendermint, may have -client specific parameters like `TrustLevel` which must be considered valid in relation -to the `Header`. The update height is not necessarily the lastest height of the light -client. Updates may fill in missing consensus state heights. - -Clients may be upgraded. The upgrade should be verified using `VerifyUpgrade`. It is not -a requirement to allow for light client upgrades. For example, the solo machine client -will simply return an error on `VerifyUpgrade`. Clients which implement upgrades -are expected to account for, but not necessarily support, planned and unplanned upgrades. - ## Client Misbehaviour IBC clients must freeze when the counterparty chain becomes byzantine and @@ -48,93 +26,6 @@ Governance may then choose to override a frozen client and provide the correct, canonical Header so that the client can continue operating after the Misbehaviour submission. -## ClientUpdateProposal - -A governance proposal may be passed to update a specified client using another client -known as the "substitute client". This is useful in unfreezing clients or updating -expired clients, thereby making the effected channels active again. Each client is -expected to implement this functionality. A client may choose to disallow an update -by a governance proposal by returning an error in the client state function 'CheckSubstituteAndUpdateState'. - -The localhost client cannot be updated by a governance proposal. - -The solo machine client requires the boolean flag 'AllowUpdateAfterProposal' to be set -to true in order to be updated by a proposal. This is set upon client creation and cannot -be updated later. - -The tendermint client has two flags update flags, 'AllowUpdateAfterExpiry' and -'AllowUpdateAfterMisbehaviour'. The former flag can only be used to unexpire clients. The -latter flag can be used to unfreeze a client and if necessary it will also unexpire the client. -It is best practice to initialize a new substitute client instead of using an existing one -This avoids potential issues of the substitute becoming frozen due to misbehaviour or the -subject client becoming refrozen due to misbehaviour not being expired at the time the -proposal passes. These boolean flags are set upon client creation and cannot be updated later. - -The `CheckSubstituteAndUpdateState` function provides the light client with its own client -store, the client store of the substitute, the substitute client state, and the intitial -height that should be used when referring to the substitute client. Most light client -implementations should copy consensus states from the substitute to the subject, but -are not required to do so. Light clients may copy informationa as they deem necessary. - -It is not recommended to use a substitute client in normal operations since the subject -light client will be given unrestricted access to the substitute client store. Governance -should not pass votes which enable byzantine light client modules from modifying the state -of the substitute. - -## 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. -An 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`). - -`Heights` that share the same revision number can be compared by simply comparing their respective `RevisionHeights`. -Heights that do not share the same revision number will only be compared using their respective `RevisionNumbers`. -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 chain-id 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 chain-ids -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 may 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 should use the concrete implementation provided in -`02-client/types` and reproduced above. - ## Connection Handshake The connection handshake occurs in 4 steps as defined in [ICS 03](https://github.com/cosmos/ibc/blob/master/spec/core/ics-003-connection-semantics). @@ -214,40 +105,6 @@ with regards to version selection in `ConnOpenTry`. Each version in a set of versions should have a unique version identifier. ::: -## Channel Handshake - -The channel handshake occurs in 4 steps as defined in [ICS 04](https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics). - -`ChanOpenInit` is the first attempt to initialize a channel on top of an existing connection. -The handshake is expected to succeed if the version selected for the existing connection is a -supported IBC version. The portID must correspond to a port already binded upon `InitChain`. -The channel identifier for the counterparty channel must be left empty indicating that the -counterparty must select its own identifier. The channel identifier is auto derived in the -format: `channel{N}` where N is the next sequence to be used. The channel is set and stored -in the INIT state upon success. The channel parameters `NextSequenceSend`, `NextSequenceRecv`, -and `NextSequenceAck` are all set to 1 and a channel capability is created for the given -portID and channelID path. - -`ChanOpenTry` is a response to a chain executing `ChanOpenInit`. If the executing chain is calling -`ChanOpenTry` after previously executing `ChanOpenInit` then the provided channel parameters must -match the previously selected parameters. If the previous channel does not exist then a channel -identifier is generated in the same format as done in `ChanOpenInit`. The connection the channel -is created on top of must be an OPEN state and its IBC version must support the desired channel -type being created (ORDERED, UNORDERED, etc). The executing chain will verify that the channel -state of the counterparty is in INIT. The executing chain will set and store the channel state -in TRYOPEN. The channel parameters `NextSequenceSend`, `NextSequenceRecv`, and `NextSequenceAck` -are all set to 1 and a channel capability is created for the given portID and channelID path only -if the channel did not previously exist. - -`ChanOpenAck` may be called on a chain when the counterparty channel has entered TRYOPEN. A -previous channel on the executing chain must exist be in either INIT or TRYOPEN state. If the -counterparty selected its own channel identifier, it will be validated in the basic validation -of `MsgChanOpenAck`. The executing chain verifies that the counterparty channel state is in -TRYOPEN. The channel is set and stored in the OPEN state upon success. - -`ChanOpenConfirm` is a response to a chain executing `ChanOpenAck`. The executing chain's -previous channel state must be in TRYOPEN. The executing chain verifies that the counterparty -channel state is OPEN. The channel is set and stored in the OPEN state upon success. ## Channel Version Negotiation @@ -346,14 +203,6 @@ commitments could be removed from channels which do not write packet acknowledgements and acknowledgements could be removed when a packet has completed its life cycle. -## Timing out Packets - -A packet may be timed out on the receiving chain if the packet timeout height or timestamp has -been surpassed on the receving chain or the channel has closed. A timed out -packet can only occur if the packet has never been received on the receiving -chain. ORDERED channels will verify that the packet sequence is greater than -the `NextSequenceRecv` on the receiving chain. UNORDERED channels will verify -that the packet receipt has not been written on the receiving chain. A timeout on channel closure will additionally verify that the counterparty channel has been closed. A successful timeout may execute application logic as appropriate. @@ -362,41 +211,4 @@ surpassed on the receiving chain for a timeout to be valid. A timeout timestamp or timeout height with a 0 value indicates the timeout field may be ignored. Each packet is required to have at least one valid timeout field. -## Closing Channels - -Closing a channel occurs in 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` will close 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 will be closed 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. - -## Port and Channel Capabilities - -## Hostname Validation - -Hostname validation is implemented as defined in [ICS 24](https://github.com/cosmos/ibc/tree/master/spec/core/ics-024-host-requirements). - -The 24-host sub-module parses and validates identifiers. It also builds -the key paths used to store IBC related information. - -A valid identifier must conatin only alphanumeric characters or the -following list of allowed characters: -".", "\_", "+", "-", "#", "[", "]", "<", ">" - -- Client identifiers must contain between 9 and 64 characters. -- Connection identifiers must contain between 10 and 64 characters. -- Channel identifiers must contain between 10 and 64 characters. -- Port identifiers must contain between 2 and 64 characters. - -## Proofs -Proofs for counterparty state validation are provided as bytes. These bytes -can be unmarshaled into proto definitions as necessary by light clients. -For example, the Tendermint light client will use the bytes as a merkle -proof where as the solo machine client will unmarshal the proof into -several layers proto definitions used for signature verficiation. diff --git a/modules/core/spec/02_state.md b/modules/core/spec/02_state.md deleted file mode 100644 index 8357f923c42..00000000000 --- a/modules/core/spec/02_state.md +++ /dev/null @@ -1,28 +0,0 @@ - - -# State - -The paths for the values stored in state is defined [here](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements#path-space). -Additionally, the SDK adds a prefix to the path to be able to aggregate the values for querying purposes. -The client type is not stored since it can be obtained through the client state. - -| Prefix | Path | Value type | -|--------|-----------------------------------------------------------------------------|----------------| -| "0/" | "clients/{identifier}/clientState" | ClientState | -| "0/" | "clients/{identifier}/consensusStates/{height}" | ConsensusState | -| "0/" | "clients/{identifier}/connections" | []string | -| "0/" | "nextClientSequence | uint64 | -| "0/" | "connections/{identifier}" | ConnectionEnd | -| "0/" | "nextConnectionSequence" | uint64 | -| "0/" | "ports/{identifier}" | CapabilityKey | -| "0/" | "channelEnds/ports/{identifier}/channels/{identifier}" | ChannelEnd | -| "0/" | "nextChannelSequence" | uint64 | -| "0/" | "capabilities/ports/{identifier}/channels/{identifier}" | CapabilityKey | -| "0/" | "nextSequenceSend/ports/{identifier}/channels/{identifier}" | uint64 | -| "0/" | "nextSequenceRecv/ports/{identifier}/channels/{identifier}" | uint64 | -| "0/" | "nextSequenceAck/ports/{identifier}/channels/{identifier}" | uint64 | -| "0/" | "commitments/ports/{identifier}/channels/{identifier}/sequences/{sequence}" | bytes | -| "0/" | "receipts/ports/{identifier}/channels/{identifier}/sequences/{sequence}" | bytes | -| "0/" | "acks/ports/{identifier}/channels/{identifier}/sequences/{sequence}" | bytes | diff --git a/modules/core/spec/03_state_transitions.md b/modules/core/spec/03_state_transitions.md deleted file mode 100644 index 518ff9247b9..00000000000 --- a/modules/core/spec/03_state_transitions.md +++ /dev/null @@ -1,106 +0,0 @@ - - -# State Transitions - -The described state transitions assume successful message exection. - -## Create Client - -`MsgCreateClient` will initialize and store a `ClientState` and `ConsensusState` in the sub-store -created using a generated client identifier. - -## Update Client - -`MsgUpdateClient` will update the `ClientState` and create a new `ConsensusState` for the -update height. - -## Misbehaviour - -`MsgSubmitMisbehaviour` will freeze a client. - -## Upgrade Client - -`MsgUpgradeClient` will upgrade the `ClientState` and `ConsensusState` to the update chain level -parameters and if applicable will update to the new light client implementation. - -## Client Update Proposal - -An Update Client Proposal will unfreeze a client (if necessary) and set an updated `ClientState`. -The light client may make optional modifications to the client prefixed store of the subject client -including copying `ConsensusStates` from the substitute to the subject. - -## Connection Open Init - -`MsgConnectionOpenInit` will initialize a connection state in INIT. - -## Connection Open Try - -`MsgConnectionOpenTry` will initialize or update a connection state to be in TRYOPEN. - -## Connection Open Ack - -`MsgConnectionOpenAck` will update a connection state from INIT or TRYOPEN to be in OPEN. - -## Connection Open Confirm - -`MsgConnectionOpenAck` will update a connection state from TRYOPEN to OPEN. - -## Channel Open Init - -`MsgChannelOpenInit` will initialize a channel state in INIT. It will create a channel capability -and set all Send, Receive and Ack Sequences to 1 for the channel. - -## Channel Open Try - -`MsgChannelOpenTry` will initialize or update a channel state to be in TRYOPEN. If the channel -is being initialized, It will create a channel capability and set all Send, Receive and Ack -Sequences to 1 for the channel. - -## Channel Open Ack - -`MsgChannelOpenAck` will update the channel state to OPEN. It will set the version and channel -identifier for its counterparty. - -## Channel Open Confirm - -`MsgChannelOpenConfirm` will update the channel state to OPEN. - -## Channel Close Init - -`MsgChannelCloseInit` will update the channel state to CLOSED. - -## Channel Close Confirm - -`MsgChannelCloseConfirm` will update the channel state to CLOSED. - -## Send Packet - -A application calling `ChannelKeeper.SendPacket` will incremenet the next sequence send and set -a hash of the packet as the packet commitment. - -## Receive Packet - -`MsgRecvPacket` will increment the next sequence receive for ORDERED channels and set a packet -receipt for UNORDERED channels. - -## Write Acknowledgement - -`WriteAcknowledgement` may be executed synchronously during the execution of `MsgRecvPacket` or -asynchonously by an application module. It writes an acknowledgement to the store. - -## Acknowledge Packet - -`MsgAcknowledgePacket` deletes the packet commitment and for ORDERED channels increments next -sequences ack. - -## Timeout Packet - -`MsgTimeoutPacket` deletes the packet commitment and for ORDERED channels sets the channel state -to CLOSED. - -## Timeout Packet on Channel Closure - -`MsgTimeoutOnClose` deletes the packet commitment and for ORDERED channels sets the channel state -to CLOSED. diff --git a/modules/core/spec/04_messages.md b/modules/core/spec/04_messages.md deleted file mode 100644 index 3728e6d6f32..00000000000 --- a/modules/core/spec/04_messages.md +++ /dev/null @@ -1,497 +0,0 @@ - - -# Messages - -In this section we describe the processing of the IBC messages and the corresponding updates to the state. - -## ICS 02 - Client - -### MsgCreateClient - -A light client is created using the `MsgCreateClient`. - -```go -type MsgCreateClient struct { - ClientState *types.Any // proto-packed client state - ConsensusState *types.Any // proto-packed consensus state - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ClientState` is empty or invalid -- `ConsensusState` is empty or invalid -- `Signer` is empty - -The message creates and stores a light client with an initial consensus state using a generated client -identifier. - -### MsgUpdateClient - -A light client is updated with a new header using the `MsgUpdateClient`. - -```go -type MsgUpdateClient struct { - ClientId string - Header *types.Any // proto-packed header - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ClientId` is invalid (not alphanumeric or not within 10-20 characters) -- `Header` is empty or invalid -- `Signer` is empty -- A `ClientState` hasn't been created for the given ID -- The client is frozen due to misbehaviour and cannot be updated -- The header fails to provide a valid update for the client - -The message validates the header and updates the client state and consensus state for the -header height. - -### MsgUpgradeClient -```go -type MsgUpgradeClient struct { - ClientId string - ClientState *types.Any // proto-packed client state - UpgradeHeight *Height - ProofUpgrade []byte - Signer string -} -``` - -This message is expected to fail if: - -- `ClientId` is invalid (not alphanumeric or not within 10-20 characters) -- `ClientState` is empty or invalid -- `UpgradeHeight` is empty or zero -- `ProofUpgrade` is empty -- `Signer` is empty -- A `ClientState` hasn't been created for the given ID -- The client is frozen due to misbehaviour and cannot be upgraded -- The upgrade proof fails - -The message upgrades the client state and consensus state upon successful validation of a -chain upgrade. - -### MsgSubmitMisbehaviour - -Submit a evidence of light client misbehaviour to freeze the client state and prevent additional packets from being relayed. - -```go -type MsgSubmitMisbehaviour struct { - ClientId string - Misbehaviour *types.Any // proto-packed misbehaviour - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ClientId` is invalid (not alphanumeric or not within 10-20 characters) -- `Misbehaviour` is empty or invalid -- `Signer` is empty -- A `ClientState` hasn't been created for the given ID -- `Misbehaviour` check failed - -The message verifies the misbehaviour and freezes the client. - -## ICS 03 - Connection - -### MsgConnectionOpenInit - -A connection is initialized on a light client using the `MsgConnectionOpenInit`. - -```go -type MsgConnectionOpenInit struct { - ClientId string - Counterparty Counterparty - Version string - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: -- `ClientId` is invalid (see naming requirements) -- `Counterparty` is empty -- 'Version' is not empty and invalid -- `Signer` is empty -- A Client hasn't been created for the given ID -- A Connection for the given ID already exists - -The message creates a connection for the given ID with an INIT state. - -### MsgConnectionOpenTry - -When a counterparty connection is initialized then a connection is initialized on a light client -using the `MsgConnectionOpenTry`. - -```go -type MsgConnectionOpenTry struct { - ClientId string - PreviousConnectionId string - ClientState *types.Any // proto-packed counterparty client - Counterparty Counterparty - CounterpartyVersions []string - ProofHeight Height - ProofInit []byte - ProofClient []byte - ProofConsensus []byte - ConsensusHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ClientId` is invalid (see naming requirements) -- `PreviousConnectionId` is not empty and invalid (see naming requirements) -- `ClientState` is not a valid client of the executing chain -- `Counterparty` is empty -- `CounterpartyVersions` is empty -- `ProofHeight` is zero -- `ProofInit` is empty -- `ProofClient` is empty -- `ProofConsensus` is empty -- `ConsensusHeight` is zero -- `Signer` is empty -- A Client hasn't been created for the given ID -- If a previous connection exists but does not match the supplied parameters. -- `ProofInit` does not prove that the counterparty connection is in state INIT -- `ProofClient` does not prove that the counterparty has stored the `ClientState` provided in message -- `ProofConsensus` does not prove that the counterparty has the correct consensus state for this chain - -The message creates a connection for a generated connection ID with an TRYOPEN State. If a previous -connection already exists, it updates the connection state from INIT to TRYOPEN. - -### MsgConnectionOpenAck - -When a counterparty connection is initialized then a connection is opened on a light client -using the `MsgConnectionOpenAck`. - -```go -type MsgConnectionOpenAck struct { - ConnectionId string - CounterpartyConnectionId string - Version string - ClientState *types.Any // proto-packed counterparty client - ProofHeight Height - ProofTry []byte - ProofClient []byte - ProofConsensus []byte - ConsensusHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ConnectionId` is invalid (see naming requirements) -- `CounterpartyConnectionId` is invalid (see naming requirements) -- `Version` is empty -- `ClientState` is not a valid client of the executing chain -- `ProofHeight` is zero -- `ProofTry` is empty -- `ProofClient` is empty -- `ProofConsensus` is empty -- `ConsensusHeight` is zero -- `Signer` is empty -- `ProofTry` does not prove that the counterparty connection is in state TRYOPEN -- `ProofClient` does not prove that the counterparty has stored the `ClientState` provided by message -- `ProofConsensus` does not prove that the counterparty has the correct consensus state for this chain - -The message sets the connection state for the given ID to OPEN. `CounterpartyConnectionId` -should be the `ConnectionId` used by the counterparty connection. - -### MsgConnectionOpenConfirm - -When a counterparty connection is opened then a connection is opened on a light client using -the `MsgConnectionOpenConfirm`. - -```go -type MsgConnectionOpenConfirm struct { - ConnectionId string - ProofAck []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `ConnectionId` is invalid (see naming requirements) -- `ProofAck` is empty -- `ProofHeight` is zero -- `Signer` is empty -- A Connection with the given ID does not exist -- `ProofAck` does not prove that the counterparty connection is in state OPEN - -The message sets the connection state for the given ID to OPEN. - -## ICS 04 - Channels - -### MsgChannelOpenInit - -A channel handshake is initiated by a chain A using the `MsgChannelOpenInit` -message. - -```go -type MsgChannelOpenInit struct { - PortId string - Channel Channel - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `Channel` is empty -- `Signer` is empty -- A Channel End exists for the given Channel ID and Port ID - -The message creates a channel on chain A with an INIT state for a generated Channel ID -and Port ID. - -### MsgChannelOpenTry - -A channel handshake initialization attempt is acknowledged by a chain B using -the `MsgChannelOpenTry` message. - -```go -type MsgChannelOpenTry struct { - PortId string - PreviousChannelId string - Channel Channel - CounterpartyVersion string - ProofInit []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `PreviousChannelId` is not empty and invalid (see naming requirements) -- `Channel` is empty -- `CounterpartyVersion` is empty -- `ProofInit` is empty -- `ProofHeight` is zero -- `Signer` is empty -- A previous channel exists and does not match the provided parameters. -- `ProofInit` does not prove that the counterparty's Channel state is in INIT - -The message creates a channel on chain B with an TRYOPEN state for using a generated Channel ID -and given Port ID if the previous channel does not already exist. Otherwise it udates the -previous channel state from INIT to TRYOPEN. - - -### MsgChannelOpenAck - -A channel handshake is opened by a chain A using the `MsgChannelOpenAck` message. - -```go -type MsgChannelOpenAck struct { - PortId string - ChannelId string - CounterpartyChannelId string - CounterpartyVersion string - ProofTry []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `ChannelId` is invalid (see naming requirements) -- `CounterpartyChannelId` is invalid (see naming requirements) -- `CounterpartyVersion` is empty -- `ProofTry` is empty -- `ProofHeight` is zero -- `Signer` is empty -- `ProofTry` does not prove that the counterparty's Channel state is in TRYOPEN - -The message sets a channel on chain A to state OPEN for the given Channel ID and Port ID. -`CounterpartyChannelId` should be the `ChannelId` used by the counterparty channel. - -### MsgChannelOpenConfirm - -A channel handshake is confirmed and opened by a chain B using the `MsgChannelOpenConfirm` -message. - -```go -type MsgChannelOpenConfirm struct { - PortId string - ChannelId string - ProofAck []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `ChannelId` is invalid (see naming requirements) -- `ProofAck` is empty -- `ProofHeight` is zero -- `Signer` is empty -- `ProofAck` does not prove that the counterparty's Channel state is in OPEN - -The message sets a channel on chain B to state OPEN for the given Channel ID and Port ID. - -### MsgChannelCloseInit - -A channel is closed on chain A using the `MsgChannelCloseInit`. - -```go -type MsgChannelCloseInit struct { - PortId string - ChannelId string - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `ChannelId` is invalid (see naming requirements) -- `Signer` is empty -- A Channel for the given Port ID and Channel ID does not exist or is already closed - -The message closes a channel on chain A for the given Port ID and Channel ID. - -### MsgChannelCloseConfirm - -A channel is closed on chain B using the `MsgChannelCloseConfirm`. - -```go -type MsgChannelCloseConfirm struct { - PortId string - ChannelId string - ProofInit []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `PortId` is invalid (see naming requirements) -- `ChannelId` is invalid (see naming requirements) -- `ProofInit` is empty -- `ProofHeight` is zero -- `Signer` is empty -- A Channel for the given Port ID and Channel ID does not exist or is already closed -- `ProofInit` does not prove that the counterparty set its channel to state CLOSED - -The message closes a channel on chain B for the given Port ID and Channel ID. - -### MsgRecvPacket - -A packet is received on chain B using the `MsgRecvPacket`. - -```go -type MsgRecvPacket struct { - Packet Packet - Proof []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `Proof` is empty -- `ProofHeight` is zero -- `Signer` is empty -- `Packet` fails basic validation -- `Proof` does not prove that the counterparty sent the `Packet`. - -The message receives a packet on chain B. - -### MsgTimeout - -A packet is timed out on chain A using the `MsgTimeout`. - -```go -type MsgTimeout struct { - Packet Packet - Proof []byte - ProofHeight Height - NextSequenceRecv uint64 - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `Proof` is empty -- `ProofHeight` is zero -- `NextSequenceRecv` is zero -- `Signer` is empty -- `Packet` fails basic validation -- `Proof` does not prove that the packet has not been received on the counterparty chain. - -The message times out a packet that was sent on chain A and never received on chain B. - -### MsgTimeoutOnClose - -A packet is timed out on chain A due to the closure of the channel end on chain B using -the `MsgTimeoutOnClose`. - -```go -type MsgTimeoutOnClose struct { - Packet Packet - Proof []byte - ProofClose []byte - ProofHeight Height - NextSequenceRecv uint64 - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `Proof` is empty -- `ProofClose` is empty -- `ProofHeight` is zero -- `NextSequenceRecv` is zero -- `Signer` is empty -- `Packet` fails basic validation -- `Proof` does not prove that the packet has not been received on the counterparty chain. -- `ProofClose` does not prove that the counterparty channel end has been closed. - -The message times out a packet that was sent on chain A and never received on chain B. - -### MsgAcknowledgement - -A packet is acknowledged on chain A using the `MsgAcknowledgement`. - -```go -type MsgAcknowledgement struct { - Packet Packet - Acknowledgement []byte - Proof []byte - ProofHeight Height - Signer sdk.AccAddress -} -``` - -This message is expected to fail if: - -- `Proof` is empty -- `ProofHeight` is zero -- `Signer` is empty -- `Packet` fails basic validation -- `Acknowledgement` is empty -- `Proof` does not prove that the counterparty received the `Packet`. - -The message acknowledges that the packet sent from chainA was received on chain B. diff --git a/modules/core/spec/05_callbacks.md b/modules/core/spec/05_callbacks.md deleted file mode 100644 index 0720b7c6232..00000000000 --- a/modules/core/spec/05_callbacks.md +++ /dev/null @@ -1,80 +0,0 @@ - - -# Callbacks - -Application modules implementing the IBC module must implement the following callbacks as found in [05-port](../05-port/types/module.go). -More information on how to implement these callbacks can be found in the [implementation guide](../../../docs/ibc/apps.md). - -```go -// IBCModule defines an interface that implements all the callbacks -// that modules must define as specified in ICS-26 -type IBCModule interface { - OnChanOpenInit( - ctx sdk.Context, - order channeltypes.Order, - connectionHops []string, - portId string, - channelId string, - channelCap *capability.Capability, - counterparty channeltypes.Counterparty, - version string, - ) error - - OnChanOpenTry( - ctx sdk.Context, - order channeltypes.Order, - connectionHops []string, - portId, - channelId string, - channelCap *capability.Capability, - counterparty channeltypes.Counterparty, - version, - counterpartyVersion string, - ) error - - OnChanOpenAck( - ctx sdk.Context, - portId, - channelId string, - counterpartyVersion string, - ) error - - OnChanOpenConfirm( - ctx sdk.Context, - portId, - channelId string, - ) error - - OnChanCloseInit( - ctx sdk.Context, - portId, - channelId string, - ) error - - OnChanCloseConfirm( - ctx sdk.Context, - portId, - channelId string, - ) error - - // OnRecvPacket must return the acknowledgement bytes - // In the case of an asynchronous acknowledgement, nil should be returned. - OnRecvPacket( - ctx sdk.Context, - packet channeltypes.Packet, - ) (*sdk.Result, []byte, error) - - OnAcknowledgementPacket( - ctx sdk.Context, - packet channeltypes.Packet, - acknowledgement []byte, - ) (*sdk.Result, error) - - OnTimeoutPacket( - ctx sdk.Context, - packet channeltypes.Packet, - ) (*sdk.Result, error) -} -``` diff --git a/modules/core/spec/README.md b/modules/core/spec/README.md deleted file mode 100644 index f6de9749b5e..00000000000 --- a/modules/core/spec/README.md +++ /dev/null @@ -1,26 +0,0 @@ - - -# `ibc core` - -## Abstract - -This paper defines the implementation of the IBC protocol on the Cosmos SDK, the -changes made to the specification and where to find each specific ICS spec within -the module. - -For the general specification please refer to the [Interchain Standards](https://github.com/cosmos/ics). - -## Contents - -1. **[Concepts](01_concepts.md)** -2. **[State](02_state.md)** -3. **[State Transitions](03_state_transitions.md)** -4. **[Messages](04_messages.md)** -5. **[Callbacks](05_callbacks.md)** -6. **[Events](06_events.md)** -7. **[Params](07_params.md)** From e58aa8684949c701b4e8442b26096d335ae01d0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Colin=20Axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Wed, 15 Dec 2021 13:42:59 +0100 Subject: [PATCH 2/6] remove broken link --- modules/light-clients/06-solomachine/spec/04_messages.md | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 modules/light-clients/06-solomachine/spec/04_messages.md diff --git a/modules/light-clients/06-solomachine/spec/04_messages.md b/modules/light-clients/06-solomachine/spec/04_messages.md deleted file mode 100644 index 465ea6229a7..00000000000 --- a/modules/light-clients/06-solomachine/spec/04_messages.md +++ /dev/null @@ -1,8 +0,0 @@ - - -# Messages - -The messages used to initialize a solo machine light client are defined in the -core sub-module [02-client](../../../core/spec/04_messages.md). From b0e508614d150e6791ddc75aa9488a00c37426fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?colin=20axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Thu, 16 Dec 2021 12:12:20 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Damian Nolan --- docs/ibc/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ibc/overview.md b/docs/ibc/overview.md index 47cca84b510..b749e8e0d20 100644 --- a/docs/ibc/overview.md +++ b/docs/ibc/overview.md @@ -65,12 +65,12 @@ IBC Client Heights are represented by the struct: ```go type Height struct { RevisionNumber uint64 - RevisionHeight uint64 + RevisionHeight uint64 } ``` The `RevisionNumber` represents the revision of the chain that the height is representing. -An revision typically represents a continuous, monotonically increasing range of block-heights. +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, From 8088d468a7a8110375c501fb742a526b6509ff9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Colin=20Axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Thu, 16 Dec 2021 12:21:42 +0100 Subject: [PATCH 4/6] remove broken link --- modules/light-clients/06-solomachine/spec/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/light-clients/06-solomachine/spec/README.md b/modules/light-clients/06-solomachine/spec/README.md index 45ad34c3a0e..0879f1bd2be 100644 --- a/modules/light-clients/06-solomachine/spec/README.md +++ b/modules/light-clients/06-solomachine/spec/README.md @@ -23,4 +23,3 @@ diversifier, and timestamp. 1. **[Concepts](01_concepts.md)** 2. **[State](02_state.md)** 3. **[State Transitions](03_state_transitions.md)** -4. **[Messages](04_messages.md)** From f1a93b58c0262794bd0d1ed746e0321f3f802b09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Colin=20Axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Fri, 17 Dec 2021 13:55:43 +0100 Subject: [PATCH 5/6] remove broken links --- docs/ibc/overview.md | 1 - modules/light-clients/06-solomachine/spec/02_state.md | 3 --- 2 files changed, 4 deletions(-) diff --git a/docs/ibc/overview.md b/docs/ibc/overview.md index b749e8e0d20..e516a3d15ea 100644 --- a/docs/ibc/overview.md +++ b/docs/ibc/overview.md @@ -292,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/light-clients/06-solomachine/spec/02_state.md b/modules/light-clients/06-solomachine/spec/02_state.md index a9ff4ea5b47..51cb1f058c6 100644 --- a/modules/light-clients/06-solomachine/spec/02_state.md +++ b/modules/light-clients/06-solomachine/spec/02_state.md @@ -7,6 +7,3 @@ order: 2 The solo machine light client will only store consensus states for each update by a header or a governance proposal. The latest client state is also maintained in the store. -These values can be found under the light client paths defined in the IBC -[core store specs](../../../core/spec/02_state.md). - From b4a7e19f973835079979a6da70abe767711074f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?colin=20axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Wed, 22 Dec 2021 10:59:57 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Carlos Rodriguez --- docs/ibc/overview.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/ibc/overview.md b/docs/ibc/overview.md index e516a3d15ea..53ad64e08e8 100644 --- a/docs/ibc/overview.md +++ b/docs/ibc/overview.md @@ -73,13 +73,13 @@ The `RevisionNumber` represents the revision of the chain that the height is rep 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, +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`). -`Heights` that share the same revision number can be compared by simply comparing their respective `RevisionHeights`. -Heights that do not share the same revision number will only be compared using their respective `RevisionNumbers`. +`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. @@ -90,26 +90,26 @@ Height{RevisionNumber: 3, RevisionHeight: 0} > Height{RevisionNumber: 2, Revisio ``` 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 chain-id 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. +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 chain-ids -in the following manner: `{chainID}-{revision_number}`. On any height-resetting upgrade, the chainID **MUST** be updated with a higher revision number +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` +- 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 may implement their own logic to verify the IBC Heights that relayers provide in their `Update`, `Misbehavior`, and +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 should use the concrete implementation provided in +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) @@ -210,16 +210,16 @@ that the module **must** claim so that they can pass in a capability to authenti 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 channels -Closing a channel occurs in 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). +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` will close a channel on the executing chain if the channel exists, it is not +`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 will be closed if the channel exists, the channel is not already closed, +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.