Guide update & release 0.4.0 (#1028)

* Added details about the help command in the guide * Bump version to 0.4.0 * Update guide to account for `start-multi` being promoted to `start` * Fix changelog * Document telemetry section of config file * Fixup documentation for global section of configuration file * Document type of each config option * Remove unsused config default method * Guide update for the query clients method. * Typo fix * Re-add Cargo.lock for proto-compiler crate * Document addition of `host` param to telemetry config * Document telemetry service * Update changelog with telemetry * Add changelog entry for #1026 * Channel worker updates * Add missing files * Update feature matrix * Update mdbook to v0.4.7 * Update mdbook to v0.4.9 * Add cosmos-sdk versions supported * Higlight compat info * Write summary of 0.4.0 release Co-authored-by: Romain Ruetschi <romain@informal.systems> Co-authored-by: Anca Zamfir <zamfiranca@gmail.com>
informalsystems · Jun 3, 2021 · 3494bbd · 3494bbd
1 parent 2647051
commit 3494bbd
Show file tree

Hide file tree

Showing 35 changed files with 539 additions and 475 deletions.
diff --git a/.github/workflows/guide.yml b/.github/workflows/guide.yml
@@ -19,7 +19,7 @@ jobs:
       - name: Setup mdbook
         uses: peaceiris/actions-mdbook@v1
         with:
-          mdbook-version: "0.4.6"
+          mdbook-version: "0.4.9"
 
       - name: Setup mdbook-mermaid
         uses: actions-rs/cargo@v1

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,12 +2,32 @@
 
 ## Unreleased
 
-Special thanks to Colin Axnér (@colin-axner) and Jongwhan Lee (@leejw51crypto)
-for raising multiple issues that helped us improve the reliability of Hermes.
+> Nothing yet.
+
+## v0.4.0
+*June 3rd, 2021*
+
+- This release of Hermes features an internal [telemetry service][telemetry]
+  which can export metrics about the relayer to Prometheus.
+- A new [relaying strategy][strategy] is now available, which enables Hermes to
+  complete channel handshakes in an event-based fashion.
+- Hermes now checks if another relayer may have already processed a packet event,
+  and will not attempt to process it itself, which improves performance.
+- The startup time of the relayer has been substantially improved.
+- The `start-multi` command has been promoted to `start`, which means
+  that the worker-based relayer is not experimental anymore.
+- A regression where Hermes would not recover after a node went down and up again was fixed.
+
+[telemetry]: https://hermes.informal.systems/telemetry.html
+[strategy]: http://hermes.informal.systems/config.html?highlight=strategy#global
+
+> Special thanks to Colin Axnér (@colin-axner) and Jongwhan Lee (@leejw51crypto)
+> for raising multiple issues that helped us improve the reliability of Hermes.
 
 ### FEATURES
 
 - [ibc-relayer]
+  - Add telemetry and Prometheus endpoint ([#868], [#1032])
   - Add support for event based channel relaying ([#822])
   - Graceful handling of packet events in the presence of multiple relayers ([#983])
 
@@ -25,8 +45,10 @@ for raising multiple issues that helped us improve the reliability of Hermes.
 ### BUG FIXES
 
 - [ibc-relayer]
-  - Fix for a client worker bug; Hermes `start` returns error if no chain is reachable ([#972])
-  - Client worker aborts gracefully if the client is expired or frozen ([#1022])
+  - Fix client worker initialization error ([#972])
+  - Fix `hermes start` panic when all chains are unreachable ([#972])
+  - Ensure expired or frozen client worker logs message and terminates ([#1022])
+  - Fix regression where Hermes would not recover after a node went down and up again ([#1026])
 
 - [gaiad-manager]
   - Import hermes keys properly even if wallet HD derivation path is set ([#975])
@@ -39,6 +61,7 @@ for raising multiple issues that helped us improve the reliability of Hermes.
   - Promote `start-multi` command to `start` ([#911])
 
 [#822]: https://github.com/informalsystems/ibc-rs/issues/822
+[#868]: https://github.com/informalsystems/ibc-rs/issues/868
 [#871]: https://github.com/informalsystems/ibc-rs/issues/871
 [#911]: https://github.com/informalsystems/ibc-rs/issues/911
 [#972]: https://github.com/informalsystems/ibc-rs/issues/972
@@ -50,6 +73,8 @@ for raising multiple issues that helped us improve the reliability of Hermes.
 [#998]: https://github.com/informalsystems/ibc-rs/issues/998
 [#1003]: https://github.com/informalsystems/ibc-rs/issues/1003
 [#1022]: https://github.com/informalsystems/ibc-rs/issues/1022
+[#1026]: https://github.com/informalsystems/ibc-rs/issues/1026
+[#1032]: https://github.com/informalsystems/ibc-rs/issues/1032
 [gaiad-manager]: https://github.com/informalsystems/ibc-rs/blob/master/scripts/gm/README.md
 [#1039]: https://github.com/informalsystems/ibc-rs/issues/1039
 
@@ -68,7 +93,8 @@ Docker images to Docker Hub.
 
 - [ibc-relayer]
   - Add support for multiple keys to the keyring ([#963])
-
+  - Add telemetry and Prometheus endpoint ([#868])
+
 - [release]
   - Released the official [Hermes image][hermes-docker] on Docker Hub ([#894])
   - Automatically deploy Docker Hub image during release ([#967])
@@ -87,6 +113,7 @@ Docker images to Docker Hub.
 
 > Nothing
 
+[#868]: https://github.com/informalsystems/ibc-rs/issues/868
 [#894]: https://github.com/informalsystems/ibc-rs/pull/894
 [#957]: https://github.com/informalsystems/ibc-rs/issues/957
 [#960]: https://github.com/informalsystems/ibc-rs/issues/960

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/guide/README.md b/guide/README.md
@@ -11,7 +11,7 @@ mdBook is a utility to create modern online books from Markdown files.
 This guide should be permanently deployed at its latest stable version at 
 [hermes.informal.systems](https://hermes.informal.systems).
 
-Current version: `0.3.2`.
+Current version: `0.4.0`.
 
 The version of this guide is aligned with the [versioning of the ibc crates](../README.md).
 

diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -1,6 +1,6 @@
 # Summary
 
-# Hermes (v0.3.2)
+# Hermes (v0.4.0)
 
 ---
 - [Introduction](./index.md)
@@ -11,16 +11,15 @@
    - [Pre-requisites](./pre_requisites.md)
    - [Installation](./installation.md)
    - [Configuration](./config.md)
+- [Telemetry](./telemetry.md)
 - [Tutorials](./tutorials/index.md)
    - [Local chains](./tutorials/local-chains/index.md)
      - [Install Gaia](./tutorials/local-chains/gaia.md)
      - [Start the local chains](./tutorials/local-chains/start.md)
      - [Identifiers](./tutorials/local-chains/identifiers.md)
      - [Connect the chains using relay paths](./tutorials/local-chains/relay-paths/index.md)
        - [Create a new path](./tutorials/local-chains/relay-paths/create-new-path.md)
-       - [Packet relaying on existing path](./tutorials/local-chains/relay-paths/existing-path.md)
-       - [Packet relaying on new path](./tutorials/local-chains/relay-paths/new-path.md)
-       - [Concurrent packet relaying on multiple paths](./tutorials/local-chains/relay-paths/multiple-paths.md)
+       - [Relay packets on multiple paths](./tutorials/local-chains/relay-paths/multiple-paths.md)
      - [Connect the chains using raw transactions](./tutorials/local-chains/raw/index.md)
        - [Configure clients](./tutorials/local-chains/raw/client.md)
        - [Connection handshake](./tutorials/local-chains/raw/connection.md)
@@ -33,7 +32,9 @@
      - [Clients](./commands/path-setup/clients.md)
      - [Connections](./commands/path-setup/connections.md)
      - [Channels](./commands/path-setup/channels.md)
-   - [Packet relaying](./commands/relaying.md)
+   - [Relaying](commands/relaying/index.md)
+     - [Packet Messages](./commands/relaying/packets.md)
+     - [Channel Open Handshake Messages](commands/relaying/channel.md)
    - [Listen mode](./commands/listen/index.md)
    - [Client upgrade](./commands/upgrade/index.md)
      - [Testing client upgrade](./commands/upgrade/test.md)

diff --git a/guide/src/commands/global.md b/guide/src/commands/global.md
@@ -3,13 +3,12 @@
 Hermes accepts global options which affect all commands.
 
 ```shell
-hermes 0.3.2
+hermes 0.4.0
 Informal Systems <hello@informal.systems>
 Implementation of `hermes`, an IBC Relayer developed in Rust.
 
 FLAGS:
     -c, --config CONFIG       path to configuration file
-    -h, --help                print help message
     -j, --json                enable JSON output
 ```
 

diff --git a/guide/src/commands/index.md b/guide/src/commands/index.md
@@ -12,7 +12,7 @@ Commands to manage keys (private keys) for each chain.
 
 Commands to manage clients, connections, channels.
 
-**[Packet Relaying](./relaying.md)**
+**[Relaying](./relaying/index.md)**
 
 Commands to start the relayer and relay packets.
 

diff --git a/guide/src/commands/path-setup/connections.md b/guide/src/commands/path-setup/connections.md
@@ -212,4 +212,4 @@ figure it out by looking up the given client on `ibc-0`.
 
 ## Non-zero Delay Connection
 
-A connection can be created with a delay period parameter. This parameter specifies a period of time that must elpase after a successful client state update and before a packet with proofs using its commitment root can pe processed on chain. For more information see [how packet delay works](../relaying.md#packet-delay) and the [connection delay specification](https://github.com/cosmos/ibc/tree/master/spec/core/ics-003-connection-semantics).
+A connection can be created with a delay period parameter. This parameter specifies a period of time that must elpase after a successful client state update and before a packet with proofs using its commitment root can pe processed on chain. For more information see [how packet delay works](../relaying/index.md#packet-delay) and the [connection delay specification](https://github.com/cosmos/ibc/tree/master/spec/core/ics-003-connection-semantics).
diff --git a/guide/src/commands/path-setup/index.md b/guide/src/commands/path-setup/index.md
@@ -11,7 +11,7 @@ This section describes a number of commands that can be used to manage clients,
 
 
 ## Create
-Use the `create` commands to create a new clients, connections and channels.
+Use the `create` commands to create new clients, connections and channels.
 
 ```shell
 USAGE:

diff --git a/guide/src/commands/queries/client.md b/guide/src/commands/queries/client.md
@@ -12,10 +12,14 @@ USAGE:
     hermes query clients <OPTIONS>
 
 DESCRIPTION:
-    Query clients
+    Query the identifiers of all clients on a chain
 
 POSITIONAL ARGUMENTS:
     chain_id                  identifier of the chain to query
+
+FLAGS:
+    -s, --src-chain-id ID     filter for clients which target a specific chain id (implies '-o')
+    -o, --omit-chain-ids      omit printing the source chain for each client (default: false)
 ```
 
 __Example__
@@ -26,10 +30,40 @@ Query all clients on `ibc-1`:
 hermes query clients ibc-1
 ```
 
-```rust
+```json
+Success: [
+    ClientChain {
+        client_id: ClientId(
+            "07-tendermint-0",
+        ),
+        chain_id: ChainId {
+            id: "ibc-0",
+            version: 0,
+        },
+    },
+    ClientChain {
+        client_id: ClientId(
+            "07-tendermint-1",
+        ),
+        chain_id: ChainId {
+            id: "ibc-2",
+            version: 2,
+        },
+    },
+]
+```
+
+Query all clients on `ibc-1` having `ibc-2` as their source chain:
+
+```shell
+hermes query clients ibc-1 -s ibc-2
+```
+
+```json
 Success: [
-    ClientId("07-tendermint-0"),
-    ClientId("07-tendermint-1"),
+    ClientId(
+        "07-tendermint-1",
+    ),
 ]
 ```