docs: Add instructions for v4 mainnet upgrade

Author: filipdjokic

docs/upgrades/upgrade-guides/v4.x-upgrade.md

@@ -0,0 +1,87 @@
+# Introducing the v4.x Protocol Release! 🚀
+
+This upgrade moved cheqd to support **Cosmos SDK v0.50 "Eden"**.
+
+**Cosmos SDK v0.50** is a long-term support version bringing major improvements in performance, developer experience, and modularity. Key features include **ABCI++** for more flexible and efficient consensus and **IAVL 1.0** for faster and more efficient data storage. It also adds **Optimistic Execution** to reduce block times and **Sign Mode Textual** for clearer, more secure transaction signing. This release sets a solid foundation for building faster, more customizable applications on cheqd.
+
+We also **enhanced our DIDs** to support a more flexible **service section**, enabling direct connections to `did:cheqd` DIDs using **DIDComm**. This enhancement brings full cheqd support for **DIDComm endpoint discovery**, making it easier for apps and SDKs like **ACA-Py** and **Credo** to integrate seamless messaging and communication.
+
+You can find more technical details about this upgrade on our [product docs page](https://docs.cheqd.io/product/network/upgrades/2025/4.x).
+
+## Actions that should be taken
+
+- If you're running your node with Cosmovisor and have the binary auto-download feature enabled, **no action is required**.
+
+- In case you run standalone node, you can download the `v4.1.1` binary from our [GitHub Releases page](https://github.com/cheqd/cheqd-node/releases/tag/v4.1.1) and replace them manually on your node.
+
+### ⚠️ Potential errors with binary auto download on Cosmovisor v1.7.1
+
+In case you are running Cosmovisor **v1.7.1**, you might see one potential error when upgrade height is reached.
+Apparently, even though binary is correctly downloaded to `/home/cheqd/.cheqdnode/cosmovisor/upgrades/v4`, the wrong file (the LICENSE file) gets copied to `bin/cheqd-noded`. As a result, your node won’t start after the upgrade.
+
+We suspect this issue is related to upstream Cosmos SDK `x/upgrade` module, and we will investigate separately of this release.
+
+> **ℹ️** This does not present a danger to your node state, but node won't start until you replace binaries.
+
+### 🛠️ How to Prevent This Issue
+
+You have two options:
+
+1) **Re-run [interactive installer](https://raw.githubusercontent.com/cheqd/cheqd-node/refs/heads/main/installer/installer.py)** to make sure you're running Cosmovisor v1.3.0 **before upgrade height is reached**. If you already used interactive installer, just make sure to download the latest one from the link above.
+
+2) Alternatively, you can **replace binaries when upgrade height is reached**. You can achieve this with one simple command:
+
+    ```bash
+        cp -P /home/cheqd/.cheqdnode/cosmovisor/upgrades/v4/cheqd-noded /home/cheqd/.cheqdnode/cosmovisor/upgrades/v4/bin/cheqd-noded
+    ```
+
+    To confirm this resolved you issue, just run this:
+
+    ```bash
+        cheqd-noded version
+    ```
+
+### Check Cosmovisor version
+
+To determine whether you need to take any action, check your current Cosmovisor version:
+
+```bash
+    cosmovisor --help
+```
+
+If you're running version **later than v1.3.0**, you will see output like this:
+
+```text
+    Available Commands:
+      add-batch-upgrade Add multiple upgrade binaries at specified heights to cosmovisor
+      add-upgrade       Add APP upgrade binary to cosmovisor
+      completion        Generate the autocompletion script for the specified shell
+      config            Display cosmovisor config.
+      help              Help about any command
+      init              Initialize a cosmovisor daemon home directory.
+      prepare-upgrade   Prepare for the next upgrade
+      run               Run an APP command.
+      show-upgrade-info Display current upgrade-info.json from <app> data directory
+      version           Display cosmovisor and APP version.
+```
+
+**In v1.3.0**, these upgrade-related commands are **not available** (add-batch-upgrade, add-upgrade, prepare-upgrade):
+
+```text
+    Available Commands:
+      completion  Generate the autocompletion script for the specified shell
+      help        Help about any command
+      init        Initializes a cosmovisor daemon home directory.
+      run         Run an APP command.
+      version     Prints the version of Cosmovisor.
+```
+
+To summarize, If you see the second (shorter) output above, you're good to go! ✅
+
+If not, refer back to the previous section and either:
+
+- Roll back to v1.3.0, or
+- Manually replace the binaries at the upgrade height.
+
+If anything's unclear or if you face any additional issues, you can always ask for support on our [#mainnet-operators](https://discord.com/channels/879754359859216394/943432923565154354) Discord channel!
+Also, follow the updates on [our status page](https://status.cheqd.net) and [🔊mainnet-upgrades](https://discord.com/channels/879754359859216394/1394975809139249215) Discord channel.