Documentation for Hermes v0.2 (#792)

* Add websocket_addr config option to the guide

* Licences & consistent badges in all crate readmes.

* Crates.io small improvs for cli

* Update guide to account for removal of global timeout property and addition of per-chain rpc_timeout property

* Remove documentation about light client config and commands

* modifiend output for command sections 3.3, 4.1.1, 4.1.2, 4.31.

* Fix typo

* Rename init-clients to init-hermes

* Update tutorial_set_new_path.md

* path

* Update tutorial_relay_two_paths.md

* Update Keys section of the guide

* Add backward compatibility note for keys format

* Document update to `listen` command

* Fix clippy - not caught by CI?

* Update sections that mention 'tx raw update-client' CLI

* Updates for query client consensus command

* Update feature matrix and layout

* Small cleanup

* Rought content for the path setup and streaming sub-sections

* Add misbehaviour skeleton and links with connection and packets guides

* Added details on misbehaviour

* Exit on misbehaviour event

* Exit on misbehaviour event or if client is already frozen

* revert header check changed for testing

* Update ft-transfer with the --receiver option

* Fix output of `create connection` in no-JSON mode

* Update `create client` and `update client` commands doc

* Fix `create client`, `update client` commands docs using Gaia v4.2.0

* Add Display instance to Order

* Comment out unused --version parameter in `create channel` command

* Update `create channel` doc

* Update clients doc

* Upgrade guide, create CLI wrapper

* Use `create client` command in upgrade doc

* Fix TOC in Packet Relaying page

* Fix broken link for upgrade guide

* Add channel version option

* Add fee denom and amount where missing

* Same format for channel order accross CLIs, update guide

* Only print command options in debug mode

* Minor changes in existing tutorials

* Minor update to ft-transfer interface

* Use default values with gumdrop

* Update documentation for multi-paths relaying

* Quick fix for multi-start

* Mention config everywhere in tutorial_relay_two_paths.md

* Re-organize the guide and check all links

* Comment out link checker for CI

* Rename upgrade pages

* Move feature_matrix under features/

* Change ft-transfer to use same param order as the other packet clis

* Output for upgrade

* Output for raw client and connection

* Output for raw channel open

* Use pretty debug output in channel handshake

* Add more output to multi-path tutorial

* Update lockfile

* Use pretty in channel open

* Use standard Debug instance for Height

* Use standard Debug instance for Height in guide

* More pretty channel messages

* Fix compilation

* Show commitment root hash as a hex-encoded string

* Update client queries

* Output for raw packet clis

* Output for channel close handshake

* Fix output for connection open

* Fix output for misbehaviour

* Update listen command output

* Update query connection guide doc

* Update query channel guide doc

* Update packet queries guide docs

* First pass at features

* Update packet queries guide docs, part 2

* Add page on global options and JSON output

* Update output on help page

* Use debug! in tx connection command

* Updates to documentation in the tutorials sections (#792)

* Next steps and a comment

* More uppercase on deletion of data folder

* Updates on features

* More variables in setup-chains

* Rename Disk keyring store to Test

* Fix ft-transfer invocation

* Update start-multi queries

Co-authored-by: Adi Seredinschi <[email protected]>
Co-authored-by: cezarad <[email protected]>
Co-authored-by: Anca Zamfir <[email protected]>
Co-authored-by: Andy Nogueira <[email protected]>

Author: 5 people

CHANGELOG.md

@@ -1,15 +1,22 @@
 # Changelog
 
 ## Unreleased Changes
+This release includes initial support for relaying over multiple paths from a single `hermes` instance.
+Adds support for relayer restart, where pending packets are cleared.
+Includes support for ordered channels, packet delay, misbehaviour detection and evidence submission, client upgrade after counterparty chain upgrades.
 
-> [TODO: high level summary]
+This release brings improvements to the relayer UX by providing new and updated commands for keys, client,
+connection and channel management.
+In addition, it simplifies the configuration of and integration with the light client.
+
+This release also finalizes initial implementation for all of ICS 004 handlers.
 
 ### FEATURES
 
 - Update to `tendermint-rs` v0.19.0 ([#798])
 
 - [ibc]
-  - Added handler(s) for sending packets ([#695]) and for recv. and ack. packets ([#736])
+  - Added handler(s) for sending packets ([#695]), recv. and ack. packets ([#736]), and timeouts ([#362])
 
 - [ibc-relayer]
   - Support for relayer restart ([#561])
@@ -77,6 +84,7 @@
 
 
 [#352]: https://github.com/informalsystems/ibc-rs/issues/352
+[#362]: https://github.com/informalsystems/ibc-rs/issues/362
 [#357]: https://github.com/informalsystems/ibc-rs/issues/357
 [#416]: https://github.com/informalsystems/ibc-rs/issues/416
 [#561]: https://github.com/informalsystems/ibc-rs/issues/561

Cargo.lock

@@ -23,13 +23,13 @@ class TxPacketSendRes:
 @cmd("tx raw ft-transfer")
 @dataclass
 class TxPacketSend(Cmd[TxPacketSendRes]):
-    src_chain_id: ChainId
     dst_chain_id: ChainId
+    src_chain_id: ChainId
     src_port: PortId
     src_channel: ChannelId
 
     def args(self) -> List[str]:
-        return [self.src_chain_id, self.dst_chain_id, self.src_port, self.src_channel, "9999", "1000"]
+        return [self.dst_chain_id, self.src_chain_id, self.src_port, self.src_channel, "9999", "1000"]
 
     def process(self, result: Any) -> TxPacketSendRes:
         entry = find_entry(result, 'SendPacket')
@@ -90,7 +90,7 @@ def process(self, result: Any) -> TxPacketAckRes:
 
 
 def packet_send(c: Config, src: ChainId, dst: ChainId, src_port: PortId, src_channel: ChannelId) -> Packet:
-    cmd = TxPacketSend(src_chain_id=src, dst_chain_id=dst,
+    cmd = TxPacketSend(dst_chain_id=dst, src_chain_id=src,
                        src_port=src_port, src_channel=src_channel)
 
     res = cmd.run(c).success()

e2e/e2e/packet.py

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

guide/book.toml

@@ -6,41 +6,49 @@
 - [Introduction](./index.md)
     - [What is Hermes?](./relayer.md)
 - [Features](./features.md)
-    - [Feature matrix](./feature_matrix.md)
+    - [Feature matrix](./features/matrix.md)
 - [Getting Started](./getting_started.md)
    - [Pre-requisites](./pre_requisites.md)
    - [Installation](./installation.md)
    - [Configuration](./config.md)
-- [Tutorials](./tutorials.md)
-   - [Two local chains](./two_chains.md)
-     - [Install Gaia](./gaia.md)
-     - [Start the local chains](./local_chains.md)
-     - [Connect the chains using raw transactions](./tutorial_raw.md)
-       - [Configure clients](./tutorial_client_raw.md)
-       - [Connection handshake](./tutorial_conn_raw.md)
-       - [Channel handshake](./tutorial_chan_open_raw.md)
-       - [Relay packets](./tutorial_packet_raw.md)
-     - [Connect the chains using relay paths](./tutorial_relay_paths.md)
-       - [New path](./tutorial_set_new_path.md)
-       - [Packet relaying on existing path](./tutorial_relay_existing_path.md)
-       - [Packet relaying on new path](./tutorial_relay_new_path.md)
-       - [Concurrent packet relaying on multiple paths](./tutorial_relay_two_paths.md)
-- [Commands Reference](./commands.md)
-   - [Keys](./keys.md)
-   - [Light clients](./light_clients.md)
-   - [Path setup and streaming](./relayer_loop.md)
-   - [Raw transactions](./transactions.md)
-     - [Client](./tx_client.md)
-     - [Connection](./tx_connection.md)
-     - [Channel Open](./tx_channel_open.md)
-     - [Channel Close](./tx_channel_close.md)
-     - [Packet](./tx_packet.md)
-   - [Queries](./queries.md)
-     - [Client](./query_client.md)
-     - [Connection](./query_connection.md)
-     - [Channel](./query_channel.md)
-     - [Packet](./query_packet.md)
-   - [Listen mode](./listen.md)
-- [Help](help.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)
+     - [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)
+       - [Channel handshake](./tutorials/local-chains/raw/channel.md)
+       - [Relay packets](./tutorials/local-chains/raw/packet.md)
+- [Commands Reference](./commands/index.md)
+   - [Global options and JSON output](./commands/global.md)
+   - [Keys](./commands/keys/index.md)
+   - [Path setup and streaming](./commands/setup-and-relaying/index.md)
+     - [Clients](./commands/setup-and-relaying/clients.md)
+     - [Connections](./commands/setup-and-relaying/connections.md)
+     - [Channels](./commands/setup-and-relaying/channels.md)
+     - [Packet relaying](./commands/setup-and-relaying/packets.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)
+   - [Raw transactions](./commands/raw/index.md)
+     - [Client](./commands/raw/client.md)
+     - [Connection](./commands/raw/connection.md)
+     - [Channel Open](./commands/raw/channel-open.md)
+     - [Channel Close](./commands/raw/channel-close.md)
+     - [Packet](./commands/raw/packet.md)
+- [Help](./help.md)
 - [Glossary](./glossary.md)
 ---

guide/src/SUMMARY.md

@@ -0,0 +1,113 @@
+# Global options
+
+The Hermes accepts global options which affect all commands.
+
+```shell
+hermes 0.1.1
+Informal Systems <[email protected]>
+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
+```
+
+The flags must be specified right after the `hermes` command and before any subcommand.
+
+__Example__
+
+To start the relayer using the configuration file at `/home/my_chain.toml` and enable JSON output:
+
+```shell
+hermes -c /home/my_chain.toml --json start ibc-0 ibc-1
+```
+
+## JSON output
+
+If the `--json` option is supplied, all relayer commands will output single-line JSON values instead of plain text.
+
+Intermediate log messages will be written to `stderr`, while the final result will be written to `stdout`.
+This allows processing only the final output using [`jq`](https://stedolan.github.io/jq/).
+To process all the output using `jq`, one can redirect `stderr` to `stdout` with `hermes --json COMMAND 2>&1 | jq`.
+
+__Example__
+
+```shell
+hermes -c /home/my_chain.toml --json create client ibc-0 ibc-1
+```
+
+```json
+{"timestamp":"Apr 13 20:46:31.921","level":"INFO","fields":{"message":"Using default configuration from: '.hermes/config.toml'"},"target":"ibc_relayer_cli::commands"}
+{"timestamp":"Apr 13 20:46:31.961","level":"INFO","fields":{"message":"running listener","chain.id":"ibc-1"},"target":"ibc_relayer::event::monitor"}
+{"timestamp":"Apr 13 20:46:31.989","level":"INFO","fields":{"message":"running listener","chain.id":"ibc-0"},"target":"ibc_relayer::event::monitor"}
+{"result":{"CreateClient":{"client_id":"07-tendermint-1","client_type":"Tendermint","consensus_height":{"revision_height":10060,"revision_number":1},"height":{"revision_height":10072,"revision_number":0}}},"status":"success"}
+```
+
+The first three lines are printed to `stderr`, while the last line with a `"result"` key is printed to `stdout`.
+
+__Example__
+
+To improve the readability, pipe all of the output to `jq`:
+
+```
+hermes -c /home/my_chain.toml --json create client ibc-0 ibc-1 2>&1 | jq
+```
+
+```json
+{
+  "timestamp": "Apr 13 20:52:26.060",
+  "level": "INFO",
+  "fields": {
+    "message": "Using default configuration from: '.hermes/config.toml'"
+  },
+  "target": "ibc_relayer_cli::commands"
+}
+{
+  "timestamp": "Apr 13 20:52:26.082",
+  "level": "INFO",
+  "fields": {
+    "message": "running listener",
+    "chain.id": "ibc-1"
+  },
+  "target": "ibc_relayer::event::monitor"
+}
+{
+  "timestamp": "Apr 13 20:52:26.088",
+  "level": "INFO",
+  "fields": {
+    "message": "running listener",
+    "chain.id": "ibc-0"
+  },
+  "target": "ibc_relayer::event::monitor"
+}
+{
+  "result": {
+    "CreateClient": {
+      "client_id": "07-tendermint-5",
+      "client_type": "Tendermint",
+      "consensus_height": {
+        "revision_height": 10364,
+        "revision_number": 1
+      },
+      "height": {
+        "revision_height": 10375,
+        "revision_number": 0
+      }
+    }
+  },
+  "status": "success"
+}
+```
+
+__Example__
+
+To extract the identifer of the newly created client above:
+
+```
+hermes -c /home/my_chain.toml --json create client ibc-0 ibc-1 | jq '.result.CreateClient.client_id'
+```
+
+```
+"07-tendermint-2"
+```

guide/src/commands.md

@@ -0,0 +1,33 @@
+# Commands
+
+The `Commands` section presents the commands current available in Hermes
+
+## Sections
+
+**[Keys](./keys/index.md)**
+
+Commands to manage keys (private keys) for each chain.
+
+**[Path Setup and Streaming](./setup-and-relaying/index.md)**
+
+Commands to manage clients, connections, channels and performing packet relaying
+
+**[Listen Mode](./listen/index.md)**
+
+Commands to listen for IBC events
+
+**[Upgrade](./upgrade/index.md)**
+
+Commands to perform client upgrade
+
+**[Monitor](./misbehaviour/index.md)**
+
+Commands to monitor clients and submit evidence of misbehaviour
+
+**[Queries](./queries/index.md)**
+
+Commands to execute queries on configured chains
+
+**[Raw Transactions](./raw/index.md)**
+
+Commands to submit individual transactions to configured chains