update core IBC docs (#7560)

* update state * add empty concept fields, update callbacks and messages * update client creation, update and upgrade section * add packet lifecycle concepts * add host and proof section * add connection handshake section * add channel handshakes * state transitions * self review fixes * Apply suggestions from code review Co-authored-by: Federico Kunze <[email protected]> * apply @fedekunze review suggestions * packet data section * Apply suggestions from code review Co-authored-by: Christopher Goes <[email protected]> * add @cwgoes and @fedekunze review suggestions * fix typos Co-authored-by: Federico Kunze <[email protected]> Co-authored-by: Christopher Goes <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
cosmos · Oct 27, 2020 · e306a85 · e306a85
1 parent 3d46c67
commit e306a85
Show file tree

Hide file tree

Showing 7 changed files with 402 additions and 69 deletions.
diff --git a/x/ibc/core/04-channel/keeper/handshake.go b/x/ibc/core/04-channel/keeper/handshake.go
@@ -381,7 +381,7 @@ func (k Keeper) ChanOpenConfirm(
 //
 // This section defines the set of functions required to close a channel handshake
 // as defined in https://github.com/cosmos/ics/tree/master/spec/ics-004-channel-and-packet-semantics#closing-handshake
-
+//
 // ChanCloseInit is called by either module to close their end of the channel. Once
 // closed, channels cannot be reopened.
 func (k Keeper) ChanCloseInit(

diff --git a/x/ibc/core/05-port/types/module.go b/x/ibc/core/05-port/types/module.go
@@ -59,6 +59,7 @@ type IBCModule interface {
 	) 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,

diff --git a/x/ibc/core/spec/01_concepts.md b/x/ibc/core/spec/01_concepts.md
diff --git a/x/ibc/core/spec/02_state.md b/x/ibc/core/spec/02_state.md
@@ -4,18 +4,22 @@ order: 2
 
 # State
 
-The paths for the values stored in state can be found [here](https://github.com/cosmos/ics/blob/master/spec/ics-024-host-requirements/README.md#path-space). Additionally, the SDK adds
-a prefix to the path to be able to aggregate the values for querying purposes.
+The paths for the values stored in state is defined [here](https://github.com/cosmos/ics/blob/master/spec/ics-024-host-requirements/README.md#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}/type"                                            | ClientType     |
-| "0/"   | "connections/{identifier}"                                             | ConnectionEnd  |
-| "0/"   | "ports/{identifier}"                                                   | CapabilityKey  |
-| "0/"   | "ports/{identifier}/channels/{identifier}"                             | ChannelEnd     |
-| "0/"   | "ports/{identifier}/channels/{identifier}/key"                         | CapabilityKey  |
-| "0/"   | "ports/{identifier}/channels/{identifier}/nextSequenceRecv"            | uint64         |
-| "0/"   | "ports/{identifier}/channels/{identifier}/packets/{sequence}"          | bytes          |
-| "0/"   | "ports/{identifier}/channels/{identifier}/acknowledgements/{sequence}" | bytes          |
+| Prefix | Path                                                                        | Value type     |
+|--------|-----------------------------------------------------------------------------|----------------|
+| "0/"   | "clients/{identifier}/clientState"                                          | ClientState    |
+| "0/"   | "clients/{identifier}/consensusStates/{height}"                             | ConsensusState |
+| "0/"   | "clients/{identifier}/connections"                                          | []string       |
+| "0/"   | "connections/{identifier}"                                                  | ConnectionEnd  |
+| "0/"   | "ports/{identifier}"                                                        | CapabilityKey  |
+| "0/"   | "channelEnds/ports/{identifier}/channels/{identifier}"                      | ChannelEnd     |
+| "0/"   | "capabilities/ports/{identifier}/channels/{identifier}/key"                 | CapabilityKey  |
+| "0/"   | "seqSends/ports/{identifier}/channels/{identifier}/nextSequenceSend"        | uint64         |
+| "0/"   | "seqRecvs/ports/{identifier}/channels/{identifier}/nextSequenceRecv"        | uint64         |
+| "0/"   | "seqAcks/ports/{identifier}/channels/{identifier}/nextSequenceAck"          | uint64         |
+| "0/"   | "commitments/ports/{identifier}/channels/{identifier}/packets/{sequence}"   | bytes          |
+| "0/"   | "receipts/ports/{identifier}/channels/{identifier}/receipts/{sequence}"     | bytes          |
+| "0/"   | "acks/ports/{identifier}/channels/{identifier}/acknowledgements/{sequence}" | bytes          |
diff --git a/x/ibc/core/spec/03_state_transitions.md b/x/ibc/core/spec/03_state_transitions.md
@@ -4,3 +4,102 @@ order: 3
 
 # 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 the given 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 and set an updated `ClientState` and a new
+`ConsensusState`.
+
+## 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/x/ibc/core/spec/04_messages.md b/x/ibc/core/spec/04_messages.md
@@ -29,9 +29,8 @@ This message is expected to fail if:
 - `Signer` is empty
 - A light client with the provided id and type already exist
 
-The message creates and stores a light client with the given ID and consensus type,
-stores the validator set as the `Commiter` of the given consensus state and stores
-both the consensus state and its commitment root (i.e app hash).
+The message creates and stores a light client with an initial consensus state for the given client
+identifier.
 
 ### MsgUpdateClient
 
@@ -51,11 +50,36 @@ This message is expected to fail if:
 - `Header` is empty or invalid
 - `Signer` is empty
 - A `ClientState` hasn't been created for the given ID
-- the header's client type is different from the registered one
-- the client is frozen due to misbehaviour and cannot be updated
+- 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 consensus state with the new
-height, commitment root and validator sets, which are then stored.
+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
 
@@ -77,8 +101,7 @@ This message is expected to fail if:
 - A `ClientState` hasn't been created for the given ID
 - `Misbehaviour` check failed
 
-The message validates the header and updates the consensus state with the new
-height, commitment root and validator sets, which are then stored.
+The message verifies the misbehaviour and freezes the client. 
 
 ## ICS 03 - Connection
 
@@ -432,7 +455,7 @@ This message is expected to fail if:
 - `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 on chain B.
+The message times out a packet that was sent on chain A and never received on chain B.
 
 ### MsgTimeoutOnClose
 
@@ -461,7 +484,7 @@ This message is expected to fail if:
 - `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 on chain B.
+The message times out a packet that was sent on chain A and never received on chain B.
 
 ### MsgAcknowledgement
 
@@ -486,4 +509,4 @@ This message is expected to fail if:
 - `Acknowledgement` is empty
 - `Proof` does not prove that the counterparty received the `Packet`.
 
-The message receives a packet on chain A.
+The message acknowledges that the packet sent from chainA was received on chain B.
diff --git a/x/ibc/core/spec/05_callbacks.md b/x/ibc/core/spec/05_callbacks.md
@@ -4,7 +4,8 @@ order: 5
 
 # Callbacks
 
-Application modules implementing the IBC module must implement the following callbacks as found in [05-port](../core/05-port/types/module.go).
+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/custom.md).
 
 ```go
 // IBCModule defines an interface that implements all the callbacks
@@ -59,6 +60,7 @@ type IBCModule interface {
 	) 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,