Add --upgrade-height parameter to upgrade client command (#2357)

Adds a flag --upgrade-height parameter that receives a Height parameter from the user that specifies the application height at which the host chain should halt before performing the client upgrade.

---

* Pull in upstream changes

* Add required `upgrade-height` flag to `upgrade client` command

* Sleep until src application height reaches the target input height

* Formatting

* Have `upgrade client` command loop until chain reaches target height

* Add gm.toml example file to guide and change thread sleep duration

* Remove reference to dev-env

* Add info's to wait loop and remove dev-env mentions from guide

* Saving progress

* Slight cleanup

* Rename src -> host

* Clean up example gm.toml

* Fix host -> reference language

* Quick fixes to the Hermes guide for testing the 'upgrade client' command

* Added new upgrade-height flag to REQUIRED flags in help output. Fixed unit tests and added new test for the new flag

* fix upgrade logic

* fmt

* naming

* Updated guide and comment for 'upgrade client' command

* Add changelog entry

* Updated 'Testing client upgrade' in Hermes guide

* naming

* implement changes to `upgrade-clients` too

* Formatting

* pass height by value

* error message fix

* Change info's to debug's

* fix race condition with node

* Change info's to debug's

* Cargo fmt

* Updated ADR 010 to include 'upgrade-height' flag for 'upgrade clients' and added a unit test for the flag

Co-authored-by: Romain Ruetschi <[email protected]>
Co-authored-by: Luca Joss <[email protected]>
Co-authored-by: Philippe Laferriere <[email protected]>

.changelog/unreleased/ibc-relayer-cli/2300-add-upgrade-height-flag-to-upgrade-client-command.md

@@ -0,0 +1,2 @@
+- Added a required flag `--upgrade-height` that halts the reference chain at the
+  specified height when performing a client upgrade ([#2300](https://github.com/informalsystems/ibc-rs/issues/2300))

docs/architecture/adr-010-unified-cli-arguments-hermes.md

@@ -35,9 +35,9 @@ The following commands are implemented, with the binary name `hermes` often omit
 * `update client --host-chain <HOST_CHAIN_ID> --client <CLIENT_ID>`
     * Optional: `[--height <REFERENCE_HEIGHT>] [--trusted-height <REFERENCE_TRUSTED_HEIGHT>]`
 
-* `upgrade client --host-chain <HOST_CHAIN_ID> --client <CLIENT_ID>`
+* `upgrade client --host-chain <HOST_CHAIN_ID> --client <CLIENT_ID> --upgrade-height <REFERENCE_UPGRADE_HEIGHT>`
 
-* `upgrade clients --reference-chain <REFERENCE_CHAIN_ID>`
+* `upgrade clients --reference-chain <REFERENCE_CHAIN_ID> --upgrade-height <REFERENCE_UPGRADE_HEIGHT>`
     * Optional: `[--host-chain <HOST_CHAIN_ID>]`
 
 ### Create a connection

guide/src/commands/upgrade/index.md

@@ -6,14 +6,20 @@ Use the `upgrade client` command to upgrade a client after a chain upgrade.
 
 ```shell
 USAGE:
-    hermes upgrade client --host-chain <HOST_CHAIN_ID> --client <CLIENT_ID>
+    hermes upgrade client --host-chain <HOST_CHAIN_ID> --client <CLIENT_ID> --upgrade-height <REFERENCE_UPGRADE_HEIGHT>
 
 DESCRIPTION:
     Upgrade an IBC client
 
 REQUIRED:
-        --client <CLIENT_ID>            Identifier of the client to be upgraded
-        --host-chain <HOST_CHAIN_ID>    Identifier of the chain that hosts the client
+        --client <CLIENT_ID>
+            Identifier of the client to be upgraded
+
+        --host-chain <HOST_CHAIN_ID>
+            Identifier of the chain that hosts the client
+
+        --upgrade-height <REFERENCE_UPGRADE_HEIGHT>
+            The height at which the reference chain halts for the client upgrade
 ```
 
 __Example__