Merge branch 'aditya/tm-light-client-docs' of github.com:cosmos/ibc-g…

…o into aditya/tm-light-client-docs

docs/docs/03-light-clients/05-tendermint/01-overview.md

@@ -9,7 +9,7 @@ slug: /ibc/light-clients/tendermint/overview
 
 ## Overview
 
-The tendermint client is the first and most deployed light client in IBC. It implements the IBC Light Client interface to track a counterparty running Comet BFT consensus. Note: Tendermint is the old name of Comet BFT which has been retained in IBC to avoid expensive migration costs.
+The tendermint client is the first and most deployed light client in IBC. It implements the IBC Light Client interface to track a counterparty running [CometBFT](https://github.com/cometbft/cometbft) consensus. Note: Tendermint is the old name of CometBFT which has been retained in IBC to avoid expensive migration costs.
 
 The tendermint client consists of two important structs that keep track of the state of the counterparty chain and allow for future updates. The `ClientState` struct contains all the parameters necessary for CometBFT header verification. The `ConsensusState`, on the other hand, is a compressed view of a particular header of the counterparty chain. Unlike off chain light clients, IBC does not store full header. Instead it stores only the information it needs to prove verification of key/value pairs in the counterparty state (ie the header AppHash), and the information necessary to use the consensus state as the next root of trust to add a new consensus state to the client (ie the header NextValidatorsHash and Timestamp). The relayer provides the full trusted header on UpdateClient, which will get checked against the compressed root-of-trust consensus state. If the trusted header matches a previous consensus state, and the trusted header and new header pass the CometBFT light client update algorithm; then the new header is compressed into a consensus state and added to the IBC client.
 
@@ -21,7 +21,7 @@ If a counterparty chain violates the CometBFT protocol in a way that is detectab
 
 ### Initialization
 
-The Tendermint light client is initialized with a ClientState that contains parameters necessary for CometBFT header verification along with a latest height and ConsensusState which encapsulates a root of trust header that will serve to verify future incoming headers from the counterparty.
+The Tendermint light client is initialized with a ClientState that contains parameters necessary for CometBFT header verification along with a latest height and ConsensusState which encapsulates the application state root of a trust header that will serve to verify future incoming headers from the counterparty.
 
 ```proto
 message ClientState {
@@ -83,12 +83,16 @@ Once the initial client state and consensus state are submitted, future consensu
 ```proto
 message Header {
   // this is the new signed header that we want to add
-  // as a consensus state to the client
+  // as a new consensus state to the ibc client. 
+  // the signed header contains the commit signatures of the `validator_set` below
   .tendermint.types.SignedHeader signed_header = 1;
 
-  // this is the 
+  // the validator set which signed the new header
   .tendermint.types.ValidatorSet validator_set      = 2;
+  // the trusted height of the consensus state which we are updating from
   ibc.core.client.v1.Height      trusted_height     = 3;
+  // the trusted validator set, the hash of the trusted validators must be equal to 
+  // `next_validators_hash` of the current consensus state
   .tendermint.types.ValidatorSet trusted_validators = 4;
 }
 ```

docs/docs/03-light-clients/05-tendermint/_category_.json

@@ -2,4 +2,4 @@
     "label": "Tendermint",
     "position": 5,
     "link": null
-  }
+  }