## IBC Tendermint Client Validator Downgrade Process

### **Overview**
This document outlines the process for downgrading a **validator set** to a **single validator (sequencer)** while ensuring **IBC compatibility**. The downgrade process involves carefully managing **validator updates** and **IBC client state** to maintain consensus and avoid issues arising from insufficient validator overlap.

> The same procedure can be followed when using an IBC attester set instead of the single sequencer as the same security and trust assumptions remain the same when making a large change to the validator set.

---

## **1. Problem Statement**
- In **CometBFT**/**Tendermint**, a block header must be signed by at least **1/3 of the trusted validators** for a client update to be considered valid.
- When transitioning from **multiple validators (e.g. 4) to a single sequencer (1)**, there is **not enough overlap** unless handled correctly.
- To ensure compatibility with existing connections the **IBC client update can still be verified** by including a consensus state where the validators signed off on the new sequencer as the next validator set.

---

## **2. Migration Process**
### **Step 1: Apply Validator Set Updates in the Cosmos SDK Application**
1. **Inject Validator Set Changes** via the Cosmos SDK's **`EndBlock`** method.
2. Modify **`ValidatorUpdates`** in `abci.ResponseEndBlock` to remove existing validators and retain only the sequencer.
3. These updates will be reflected in the **next block's `NextValidatorsHash`** and subsequently in the committed block header.

### **Step 2: Commit the Upgrade Block**
1. **Execute the block commit process**, which applies the validator updates from the previous step.
2. **Update the validator set** on the next block, ensuring that the change is reflected in `NextValidatorsHash`.
3. **Synchronize the application state** to track the new validator set accurately.

### **Step 3: IBC Client Update with the New Validator Set**
1. **IBC Clients must trust the last block before the validator set change**.
2. The client update should be submitted when `NextValidatorsHash` reflects the sequencer.
3. Submit the update to the IBC client on the counterparty chain. Ensure that the counterparty chain processes the IBC update correctly by verifying **1/3+** of the trusted validator set has signed the new commit.

### **Step 4: Finalize Migration to Single Validator (Sequencer)**
1. The validator set update **takes effect in the second block after submission** i.e. **H+2** (see [CometBFT abci spec](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#when-does-cometbft-call-finalizeblock)).
2. Once the sequencer is the sole validator, subsequent blocks should contain:
- `ValsHash: sequencer`
- `NextValsHash: sequencer`
3. The IBC client should now be able to update using the new validator set.

---

## **3. Summary of Key Transitions**

| **Block** | **ValsHash** | **NextValsHash** | **Description** |
|-----------|------------|----------------|----------------|
| `H` | `Original Validators` | `Original Validators` | ABCI FinalizeBlock returns validator updates to downgrade to sequencer |
| `H+1` | `Original Validators` | `Sequencer` | Validator updates reflected in `nextValsHash`. IBC update will accept `Header` at `H+1` and set `nextValsHash` as sequencer |
| `H+2` | `Sequencer` | `Sequencer` | IBC can now accept this Header using only the sequencer |

---

## **4. Conclusion**
- **IBC Clients normally require a 1/3 validator overlap**, but this ensures a **safe transition to a single sequencer** by anchoring trust at the right height.
- **Validator set changes are reflected across multiple blocks** (`nextValsHash` and `valsHash` propagation).
- **IBC updates must be performed at the correct height** to ensure the trusted consensus state is valid.

This approach enables smooth validator-to-sequencer migration without breaking IBC compatibility. Similarly, when using an IBC attester set in place of the single sequencer, the same **1/3** overlap trust requirements remain in place and the same downgrade procedure can be followed.

---

> See the following test code using IBC testing library to demonstrate the validator set downgrade process. https://github.com/damiannolan/ibc-go/pull/1