# Checking Header, Updating State, & Pruning

## High Level Scope
The `ClientState.CheckHeaderAndUpdateState()` method has a lot going on but there are really a few core things happening here.

- Check if the provided `Header` is invalid
- Client or header provided are not parseable
- Header is invalid
- Header height is less than or equal to the trusted header height
- Header revision is not equal to trusted header revision
- Header validator set commit verification fails
- Header timestamp is past the trusting period
- Header timestamp is less than or equal to the consensus state timestamp
- Update client state by creating a consensus state for either
- A past height that was skipped during bisection(this may only be relevant to the TM client)
- A future height which is greater than the latest client state height
- Misbehavior detection
- Enforces invariants which are checked when updating the client
- Broken invariants cause the client to enter a frozen state which requires an on chain governance proposal to fix
- Pruning
- Retrieve the oldest consensus state for this client identifier and check if expired
- Iterate over consensus states starting at oldest and prune all invalid states along with any related metadata

## General Code Flow

The method accepts a `Header` argument which is the newly proposed header passed over IBC from the counterparty via `MsgUpdateClient`.

Check if the store already has a consensus state for this headers height. If one exists we need to check if the existing consensus state in the store is equal to the newly proposed one. If they are not exactly the same then we need to submit a misbehavior and freeze the light client.

If a consesnsus state is not in the store for this header then we need to now validate this new header and perform any checks that could make this header unacceptable.

Check that previous and next consensus state timestamps are monotonic.

Check the earliest consensus state in store to determine if its expired. If expired set the prune height so that the consensus state can be deleted along with all associated metadata. Iterate through the consensus states in ascending order and mark the prune height accordingly.

Apply the update to the client state and return.

## Update Client
A client is updated by passing a new `Header` to the `CheckHeaderAndUpdateState` call.
To quote the spec here, "The client identifier is used to point to the stored ClientState that the logic will update. When a new Header is verified with the stored ClientState's validity predicate and ConsensusState, the client MUST update its internal state accordingly, possibly finalising commitment roots and updating the signature authority logic in the stored consensus state."

When an on chain light client is created via `MsgCreateClient` a `trusting period` is set which acts as a time duration in which a valid header must be submitted to update the client's state. This `trusting period` is an arbitrary value which much be greater than 0 but less than or equal to the associated chain's unbonding period.

If a client is not updated within this `trusting period` then the client becomes expired and an on chain governance proposal must be created to bring the client back to an active state.

## Misbehavior Detection

The invariants that are checked, in the case of the Tendermint client, seem to fall into two categories. The first being, if a valid update creates a different consensus state for an already existing height. The second, a valid update breaks time monotonicity with respected to its neighboring consensus states.

Detection of either of these invariants being broken results in the client being frozen which then requires an on chain governance proposal to unfreeze.

## Pruning Consensus States

When a valid update request comes in, the oldest consensus state in the store is fetched. If this consensus state is expired/invalid (i.e. it's trusting period is outside of the acceptable value in relation to consensus state time) then it is pruned from the store. An iterator will be used to step through the consensus states in the store until the *oldest* yet *valid* consensus state is found. All expired states observed before arriving at the *oldest* yet *valid* consensus state are pruned from the store.

## Notes
All props belong to the IBC team, I just aggregated a bunch of information that is readily available throughout the IBC spec and the Tendermint light client implementation.

https://github.com/cosmos/ibc-go/blob/main/modules/light-clients/07-tendermint
https://github.com/cosmos/ibc/tree/main/spec