Guide refactoring and new tutorials

.github/workflows/guide.yml

@@ -38,6 +38,13 @@ jobs:
           version: latest
           use-tool-cache: true
 
+      - name: Install mdbook-template
+        uses: actions-rs/install@v0.1
+        with:
+          crate: mdbook-template
+          version: latest
+          use-tool-cache: true
+
       - name: Install mdbook-toc
         uses: actions-rs/install@v0.1
         with:

guide/README.md

@@ -4,8 +4,7 @@ Hermes is the name of the binary that comes packaged with
 [IBC Relayer CLI](https://crates.io/crates/ibc-relayer-cli) crate.
 
 This directory comprises a comprehensive guide to Hermes.
-In order to build and view this guide you need to install [`mdBook`]
-(https://github.com/rust-lang/mdBook).
+In order to build and view this guide you need to install [`mdBook`](https://github.com/rust-lang/mdBook).
 mdBook is a utility to create modern online books from Markdown files.
 
 This guide should be permanently deployed at its latest stable version at
@@ -69,7 +68,7 @@ Please check the [mdBook documentation](https://rust-lang.github.io/mdBook/index
 Basically if you want to add new content to the guide, just add an entry to the `SUMMARY.md` Markdown file which is the TOC page. Then create a page for the entry you've added to the `SUMMARY.md` page. If you don't create the page, but save the `SUMMARY.md` file and build again, `mdBook` will create the page automatically for you.
 
 #### Local development
-If you are adding content using your favorite IDE and have a terminal opened running `mdbook serve`, it provides a convenient watch functionality so any changes detected on local files will trigger another build and if you refresh the guide on your browser they will be shown there.
+If you are adding content using your favorite IDE and have a terminal opened running `mdbook serve`, it provides a convenient watch functionality, so any changes detected on local files will trigger another build and if you refresh the guide on your browser they will be shown there.
 
 #### Submit your changes
 Once you finish adding the new content just commit your changes (`git commit`) and push them to the respository (`git push`).

guide/book.toml

@@ -17,3 +17,6 @@ additional-js = ["mermaid.min.js", "mermaid-init.js"]
 
 # Uncomment to trigger the link check
 # [output.linkcheck]
+
+[preprocessor.template]
+

guide/src/SUMMARY.md

@@ -1,59 +1,74 @@
 # Summary
 
-# Hermes (v1.0.0)
+# Hermes v1.0.0
 
 ---
 - [Introduction](./index.md)
-    - [What is Hermes?](./relayer.md)
-- [Features](./features.md)
-    - [Feature matrix](./features/matrix.md)
-- [Getting Started](./getting_started.md)
-   - [Pre-requisites](./pre_requisites.md)
-   - [Installation](./installation.md)
-   - [Configuration](./config.md)
-     - [Example Configuration](./example-config.md)
-- [Telemetry](./telemetry.md)
-    - [Operators guide](./telemetry/operators.md)
-    - [Integration](./telemetry/integration.md)
-- [REST API](./rest-api.md)
+- [Quick start](./quick-start/index.md)
+   - [Prerequisites](./quick-start/pre-requisites.md)
+   - [Installation](./quick-start/installation.md)
 - [Tutorials](./tutorials/index.md)
+   - [Prerequisites for local chains](./tutorials/pre-requisites/index.md)
+     - [Install Gaia](./tutorials/pre-requisites/gaia.md)
+     - [Install Gaiad Manager](./tutorials/pre-requisites/gaiad-manager.md)
    - [Local chains](./tutorials/local-chains/index.md)
-     - [Install Gaia](./tutorials/local-chains/gaia.md)
-     - [Install Gaiad Manager](./tutorials/local-chains/gaiad-manager.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)
-       - [Relay packets on multiple paths](./tutorials/local-chains/relay-paths/multiple-paths.md)
-- [Commands Reference](./commands/index.md)
-   - [Global options and JSON output](./commands/global.md)
-   - [Keys](./commands/keys/index.md)
-   - [Config](./commands/config.md)
-   - [Path setup](./commands/path-setup/index.md)
-     - [Clients](./commands/path-setup/clients.md)
-     - [Connections](./commands/path-setup/connections.md)
-     - [Channels](./commands/path-setup/channels.md)
-   - [Relaying](commands/relaying/index.md)
-     - [Packet Messages](./commands/relaying/packets.md)
-     - [Handshake Messages](commands/relaying/handshakes.md)
-     - [Clearing Packets](commands/relaying/clear.md)
-   - [Listen mode](./commands/listen/index.md)
-   - [Client upgrade](./commands/upgrade/index.md)
-     - [Testing client upgrade](./commands/upgrade/test.md)
-   - [Misbehaviour](./commands/misbehaviour/index.md)
-   - [Queries](./commands/queries/index.md)
-     - [Client](./commands/queries/client.md)
-     - [Connection](./commands/queries/connection.md)
-     - [Channel](./commands/queries/channel.md)
-     - [Packet](./commands/queries/packet.md)
-     - [Tx](./commands/queries/tx.md)
-     - [Transfer](./commands/queries/transfer.md)
-   - [Transactions](./commands/tx/index.md)
-     - [Connection](./commands/tx/connection.md)
-     - [Channel Open](./commands/tx/channel-open.md)
-     - [Channel Close](./commands/tx/channel-close.md)
-     - [Packet](./commands/tx/packet.md)
-     - [Upgrade](./commands/tx/upgrade.md)
-- [Help](./help.md)
+     - [Start the local chains](./tutorials/local-chains/start-local-chains.md)
+     - [Add a new relay path](./tutorials/local-chains/add-a-new-relay-path.md)
+     - [Start relaying](./tutorials/local-chains/start-relaying.md)
+    - [More Local Chains](./tutorials/more-chains/index.md)
+      - [Start the local chains](./tutorials/more-chains/start-local-chains.md)
+      - [Build the topology](./tutorials/more-chains/build-the-topology.md)
+      - [Start relaying](./tutorials/more-chains/start-relaying.md)
+      - [Add new instances of Hermes](./tutorials/more-chains/concurrent-instances.md)
+    - [Relaying in production](./tutorials/production/index.md)
+      - [Set up the monitoring platform](./tutorials/production/setup-grafana.md)
+      - [Set up Hermes](./tutorials/production/setup-hermes.md)
+      - [Start relaying](./tutorials/production/start-relaying.md)
+
+- [Advanced](./advanced/index.md)
+    - [Features](./advanced/features.md)
+    - [Troubleshooting](./advanced/troubleshooting/index.md)
+        - [Help Command](./advanced/troubleshooting/help-command.md)
+        - [Profiling](./advanced/troubleshooting/profiling.md)
+        - [Log level](./advanced/troubleshooting/log-level.md)
+        - [Patch Gaia](./advanced/troubleshooting/patch-gaia.md)
+        - [Inspecting the relayer's state](./advanced/troubleshooting/inspect.md)
+- [Documentation](./documentation/index.md)
+    - [Configuration](./documentation/configuration/index.md)
+        - [Configure Hermes](./documentation/configuration/configure-hermes.md)
+        - [Description of the parameters](./documentation/configuration/description.md)
+    - [Telemetry](./documentation/telemetry/index.md)
+        - [Operators guide](./documentation/telemetry/operators.md)
+        - [Integration](./documentation/telemetry/integration.md)
+    - [REST API](./documentation/rest-api.md)
+    - [Commands Reference](./documentation/commands/index.md)
+      - [Global options and JSON output](./documentation/commands/global.md)
+      - [Keys](./documentation/commands/keys/index.md)
+      - [Config](./documentation/commands/config.md)
+      - [Path setup](./documentation/commands/path-setup/index.md)
+        - [Clients](./documentation/commands/path-setup/clients.md)
+        - [Connections](./documentation/commands/path-setup/connections.md)
+        - [Channels](./documentation/commands/path-setup/channels.md)
+      - [Relaying](documentation/commands/relaying/index.md)
+        - [Packet Messages](./documentation/commands/relaying/packets.md)
+        - [Handshake Messages](documentation/commands/relaying/handshakes.md)
+        - [Clearing Packets](documentation/commands/relaying/clear.md)
+      - [Listen mode](./documentation/commands/listen/index.md)
+      - [Client upgrade](./documentation/commands/upgrade/index.md)
+        - [Testing client upgrade](./documentation/commands/upgrade/test.md)
+      - [Misbehaviour](./documentation/commands/misbehaviour/index.md)
+      - [Queries](./documentation/commands/queries/index.md)
+        - [Client](./documentation/commands/queries/client.md)
+        - [Connection](./documentation/commands/queries/connection.md)
+        - [Channel](./documentation/commands/queries/channel.md)
+        - [Packet](./documentation/commands/queries/packet.md)
+        - [Tx](./documentation/commands/queries/tx.md)
+        - [Transfer](./documentation/commands/queries/transfer.md)
+      - [Transactions](./documentation/commands/tx/index.md)
+        - [Connection](./documentation/commands/tx/connection.md)
+        - [Channel Open](./documentation/commands/tx/channel-open.md)
+        - [Channel Close](./documentation/commands/tx/channel-close.md)
+        - [Packet](./documentation/commands/tx/packet.md)
+        - [Upgrade](./documentation/commands/tx/upgrade.md)
 - [Glossary](./glossary.md)
 ---

guide/src/features/matrix.md → guide/src/advanced/features.md

@@ -1,6 +1,65 @@
-# Feature Matrix
-This section gives more details about the features and implementation status 
-of Hermes in comparison with the [cosmos-go-relayer].
+# Features
+
+This section includes a summary of the supported and planned features. It also includes a feature matrix which compares `hermes` to the [cosmos-go-relayer].
+
+> **Cosmos SDK & IBC compatibility:**
+> Hermes supports Cosmos SDK chains implementing the [IBC protocol v1][ibcv1-proto] protocol specification.
+> Cosmos SDK versions `0.41.3` through `0.45.x` are officially supported.
+> IBC-go versions `1.1.*` thorough `3.*` are officially supported.
+> In case Hermes finds an incompatible SDK or IBC-go version, it will output a log warning upon initialization as part of the `start` command or upon `health-check` command.
+
+---
+
+## Supported Features
+
+- Basic features
+    - Create and update clients.
+    - Refresh clients to prevent expiration.
+    - Establish connections with new or existing clients.
+    - Establish channels with new or existing connection.
+    - Channel closing handshake.
+    - Relay packets, acknowledgments, timeout and timeout-on-close packets, with zero or non-zero delay.
+    - Queries for all objects.
+- Packet relaying over:
+    - multiple paths, for the chains in `config.toml`.
+- Restart support:
+    - Clear packets.
+    - Resume channel handshake if configured to relay `all`.
+    - Resume connection handshake if configured to relay `all`.
+- Client upgrade:
+    - Upgrading clients after a counterparty chain has performed an upgrade for IBC breaking changes.
+- Packet delay:
+    - Establish path over non-zero delay connection.
+    - Relay all packets with the specified delay.
+- Interchain Accounts & Interchain Security
+- Monitor and submit misbehaviour for clients
+    - Monitor client updates for misbehaviour (fork and BFT time violation).
+    - Submit misbehaviour evidence to the on-chain IBC client.
+    > Misbehaviour submission to full node not yet supported.
+- Individual commands that build and send transactions for:
+    - Creating and updating IBC Tendermint light clients.
+    - Sending connection open handshake messages.
+    - Sending channel open handshake messages.
+    - Sending channel closing handshake messages.
+    - Initiating a cross chain transfer (mainly for testing).
+    - Relaying sent packets, acknowledgments and timeouts.
+    - Automatically generate a configuration file from the [chain-registry](https://github.com/cosmos/chain-registry)
+    - Client upgrade.
+- Channel handshake for existing channel that is not in `Open` state.
+- Connection handshake for existing connection that is not in `Open` state.
+- Telemetry support.
+
+## Upcoming / Unsupported Features
+
+Planned features:
+- Interchain Queries
+- Non-SDK support
+- Relay from all IBC events, including governance upgrade proposal
+- Dynamic & automatic configuration management
+
+## Features matrix
+
+---
 
 __Legend__:
 
@@ -17,6 +76,7 @@ __Legend__:
 | `.._<msg>_A`      | building and sending `msg` from a command that scans chain state                                 |
 | `.._<msg>_P`      | building and sending `msg` from IBC event; doesn't apply to `.._Init` and `FT_Transfer` features |
 
+--- 
 __Feature comparison between Hermes and the Go relayer__ 
 
 | Features \      Status | Hermes | Cosmos Go | Feature Details  |
@@ -68,5 +128,5 @@ __Feature comparison between Hermes and the Go relayer__
 | REST API              | ✅    | ❌     | REST API to interact with the relayer 
 
 
-
 [cosmos-go-relayer]: https://github.com/cosmos/relayer
+[ibcv1-proto]: https://github.com/cosmos/ibc

guide/src/advanced/index.md

@@ -0,0 +1,13 @@
+# Advanced
+
+Acquire advanced knowledges about `hermes`. In this section, we present a summary of the Hermes' features compared to other relayer implementations, and we provide general guidelines for troubleshooting. 
+
+---
+
+## Sections
+
+- **[Features](./features.md)**
+    * Learn about Hermes' features and how it compares to another relayer implementation.
+
+- **[Troubleshooting](./troubleshooting/index.md)**
+    * Learn the general guidelines regarding troubleshooting.

guide/src/advanced/troubleshooting/help-command.md

@@ -0,0 +1,87 @@
+# Help command
+
+The CLI comprises a special `help` command, which accepts as parameter other commands, and provides guidance on what is the correct way to invoke those commands.
+
+> __NOTE__: This special `help` command is preferred as it will display the full help
+> message.
+
+For instance,
+
+```shell
+hermes help create
+```
+
+will provide details about all the valid invocations of the `create` CLI command.
+
+```
+USAGE:
+    hermes create <SUBCOMMAND>
+
+DESCRIPTION:
+    Create objects (client, connection, or channel) on chains
+
+SUBCOMMANDS:
+    channel       Create a new channel between two chains
+    client        Create a new IBC client
+    connection    Create a new connection between two chains
+    help          Print this message or the help of the given subcommand(s)
+```
+
+This can provide further specific guidance if we add additional parameters, e.g., 
+
+```shell
+hermes help create channel
+```
+
+```shell
+USAGE:
+    hermes create channel [OPTIONS] --a-chain <A_CHAIN_ID> --a-connection <A_CONNECTION_ID> --a-port <A_PORT_ID> --b-port <B_PORT_ID>
+
+    hermes create channel [OPTIONS] --a-chain <A_CHAIN_ID> --b-chain <B_CHAIN_ID> --a-port <A_PORT_ID> --b-port <B_PORT_ID> --new-client-connection
+
+DESCRIPTION:
+    Create a new channel between two chains.
+
+    Can create a new channel using a pre-existing connection or alternatively, create a new client and a
+    new connection underlying the new channel if a pre-existing connection is not provided.
+
+OPTIONS:
+        --channel-version <VERSION>
+            The version for the new channel
+
+            [aliases: chan-version]
+
+        --new-client-connection
+            Indicates that a new client and connection will be created underlying the new channel
+
+            [aliases: new-client-conn]
+
+        --order <ORDER>
+            The channel ordering, valid options 'unordered' (default) and 'ordered'
+
+            [default: ORDER_UNORDERED]
+
+        --yes
+            Skip new_client_connection confirmation
+
+FLAGS:
+        --a-chain <A_CHAIN_ID>
+            Identifier of the side `a` chain for the new channel
+
+        --a-connection <A_CONNECTION_ID>
+            Identifier of the connection on chain `a` to use in creating the new channel
+
+            [aliases: a-conn]
+
+        --a-port <A_PORT_ID>
+            Identifier of the side `a` port for the new channel
+
+        --b-chain <B_CHAIN_ID>
+            Identifier of the side `b` chain for the new channel
+
+        --b-port <B_PORT_ID>
+            Identifier of the side `b` port for the new channel
+```
+
+Additionally, the `-h`/`--help` flags typical for CLI applications work on
+all commands.

guide/src/advanced/troubleshooting/index.md

@@ -0,0 +1,25 @@
+# Troubleshooting
+
+This section provides guidelines regarding troubleshooting. 
+
+---
+
+## Sections
+
+- **[Help Command][help]**
+    * Learn about `hermes help` command, providing a CLI documentation for all `hermes` commands.
+- **[Profiling][profiling]**
+    * Learn how to `profile` your relayer binary to identify slow methods and bottlenecks.
+- **[Parametrize the log level][log-level]**
+    * Learn how to configure the `log-level` to help with debugging.
+- **[Patch Gaia][patching]**
+    * Learn how to `patch` your local gaia chain(s) to enable some corner-case methods (e.g., channel close).
+- **[Inspecting the relayer state][relayer state]**
+    * Learn how to `inspect` the state of your relayer.
+
+
+[help]: ./help-command.md
+[log-level]: ./log-level.md
+[profiling]: ./profiling.md
+[patching]: ./patch-gaia.md
+[relayer state]: ./inspect.md