From b7fb4f169dd1ecf25fee83f036c6abca59bc53c7 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 16:13:04 +0100 Subject: [PATCH] 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 * remove broken link * remove broken links * Apply suggestions from code review Co-authored-by: Carlos Rodriguez Co-authored-by: Damian Nolan Co-authored-by: Carlos Rodriguez --- .../spec/06_events.md => docs/ibc/events.md | 4 +- docs/ibc/overview.md | 90 +++- .../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 - .../06-solomachine/spec/02_state.md | 3 - .../06-solomachine/spec/04_messages.md | 8 - .../06-solomachine/spec/README.md | 1 - 14 files changed, 101 insertions(+), 947 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 delete mode 100644 modules/light-clients/06-solomachine/spec/04_messages.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..53ad64e08e8 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. +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 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)** 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). - 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). 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)**