Documentation update for v0.3 (informalsystems#904)

* First pass changes

* update for issue 785, allow_update...set to true

* Changelog fix

* Fix query channels, API already returns domain types

* Remove redundant parameters and checks from query unreceived

* Feature matrix update

* Update Hermes version to 0.3.0 in the guide.

* Cleanup of start-multi tutorial

* Move Packet Relaying section one level up and add start-multi doc

* Rename setup-and-relaying folder to path-setup

* Add link to start-multi tutorial

* Typos and clarifications

* Disable linkcheck

* Mention open channels in start-multi ref

* Wait for ft-transfer before starting the relayer loop

* Updated features.md

* hermes help output

Co-authored-by: Adi Seredinschi <adi@informal.systems>
Co-authored-by: Romain Ruetschi <romain@informal.systems>

CHANGELOG.md

@@ -55,14 +55,13 @@ Jongwhan Lee (@leejw51crypto) ([#878]).
 [#840]: https://github.com/informalsystems/ibc-rs/issues/840
 [#851]: https://github.com/informalsystems/ibc-rs/issues/851
 [#854]: https://github.com/informalsystems/ibc-rs/issues/854
-[#861]: https://github.com/informalsystems/ibc-rs/issues/861
 [#862]: https://github.com/informalsystems/ibc-rs/issues/862
 [#863]: https://github.com/informalsystems/ibc-rs/issues/863
 [#869]: https://github.com/informalsystems/ibc-rs/issues/869
 [#871]: https://github.com/informalsystems/ibc-rs/issues/871
+[#873]: https://github.com/informalsystems/ibc-rs/issues/873
 [#878]: https://github.com/informalsystems/ibc-rs/issues/878
 [#909]: https://github.com/informalsystems/ibc-rs/issues/909
-[#873]: https://github.com/informalsystems/ibc-rs/issues/873
 
 ## v0.2.0
 *April 14th, 2021*

e2e/e2e/packet.py

@@ -132,27 +132,25 @@ def process(self, result: Any) -> TxPacketAckRes:
 @cmd("query packet unreceived-packets")
 @dataclass
 class QueryUnreceivedPackets(Cmd[List[int]]):
-    dst_chain_id: ChainId
-    src_chain_id: ChainId
-    src_port: PortId
-    src_channel: ChannelId
+    chain: ChainId
+    port: PortId
+    channel: ChannelId
 
     def args(self) -> List[str]:
-        return [self.dst_chain_id, self.src_chain_id, self.src_port, self.src_channel]
+        return [self.chain, self.port, self.channel]
 
     def process(self, result: Any) -> List[int]:
         return from_dict(List[int], result)
 
 
 def query_unreceived_packets(
     c: Config,
-    dst: ChainId,
-    src: ChainId,
-    src_port: PortId,
-    src_channel: ChannelId,
+    chain: ChainId,
+    port: PortId,
+    channel: ChannelId,
 ) -> List[int]:
     cmd = QueryUnreceivedPackets(
-        dst_chain_id=dst, src_chain_id=src, src_port=src_port, src_channel=src_channel)
+        chain=chain, port=port, channel=channel)
 
     return cmd.run(c).success()
 
@@ -162,27 +160,25 @@ def query_unreceived_packets(
 @cmd("query packet unreceived-acks")
 @dataclass
 class QueryUnreceivedAcks(Cmd[List[int]]):
-    dst_chain_id: ChainId
-    src_chain_id: ChainId
-    src_port: PortId
-    src_channel: ChannelId
+    chain: ChainId
+    port: PortId
+    channel: ChannelId
 
     def args(self) -> List[str]:
-        return [self.dst_chain_id, self.src_chain_id, self.src_port, self.src_channel]
+        return [self.chain, self.port, self.channel]
 
     def process(self, result: Any) -> List[int]:
         return from_dict(List[int], result)
 
 
 def query_unreceived_acks(
     c: Config,
-    dst: ChainId,
-    src: ChainId,
-    src_port: PortId,
-    src_channel: ChannelId,
+    chain: ChainId,
+    port: PortId,
+    channel: ChannelId,
 ) -> List[int]:
     cmd = QueryUnreceivedAcks(
-        dst_chain_id=dst, src_chain_id=src, src_port=src_port, src_channel=src_channel)
+        chain=chain, port=port, channel=channel)
 
     return cmd.run(c).success()
 

e2e/run.py

@@ -55,30 +55,32 @@ def loop(c: Config):
 
     # 3. verify the expected number of unreceived packets and acks on each channel end
 
-    # hermes query packet unreceived-packets ibc-0 ibc-1 transfer channel-1
+    # hermes query packet unreceived-packets ibc-0 transfer channel-0
     unreceived = packet.query_unreceived_packets(
-        c, src=IBC_1, dst=IBC_0, src_port=TRANSFER, src_channel=IBC_1_CHANNEL)
+        c, chain=IBC_0, port=TRANSFER, channel=IBC_0_CHANNEL)
 
     assert (len(unreceived) == 3), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-acks ibc-0 ibc-1 transfer channel-1
+    # hermes query packet unreceived-acks ibc-1 transfer channel-1
     unreceived = packet.query_unreceived_acks(
-        c, src=IBC_1, dst=IBC_0, src_port=TRANSFER, src_channel=IBC_1_CHANNEL)
+        c, chain=IBC_1, port=TRANSFER, channel=IBC_1_CHANNEL)
 
     assert (len(unreceived) == 2), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-packets ibc-1 ibc-0 transfer channel-0
+    # hermes query packet unreceived-packets ibc-1 transfer channel-1
     unreceived = packet.query_unreceived_packets(
-        c, src=IBC_0, dst=IBC_1, src_port=TRANSFER, src_channel=IBC_0_CHANNEL)
+        c, chain=IBC_1, port=TRANSFER, channel=IBC_1_CHANNEL)
 
     assert (len(unreceived) == 4), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-acks ibc-1 ibc-0 transfer channel-0
+    # hermes query packet unreceived-acks ibc-0 transfer channel-0
     unreceived = packet.query_unreceived_acks(
-        c, src=IBC_0, dst=IBC_1, src_port=TRANSFER, src_channel=IBC_0_CHANNEL)
+        c, chain=IBC_0, port=TRANSFER, channel=IBC_0_CHANNEL)
 
     assert (len(unreceived) == 2), (unreceived, "unreceived packet mismatch")
 
+    sleep(5.0)
+
     # 4. start relaying on the channel - it should clear the unreceived packets
     proc = relayer.start(c, src=IBC_0, dst=IBC_1,
                          src_port=TRANSFER, src_channel=IBC_0_CHANNEL)
@@ -95,27 +97,27 @@ def loop(c: Config):
 
     sleep(10.0)
 
-    # hermes query packet unreceived-packets ibc-0 ibc-1 transfer channel-1
+    # hermes query packet unreceived-packets ibc-1 transfer channel-1
     unreceived = packet.query_unreceived_packets(
-        c, src=IBC_1, dst=IBC_0, src_port=TRANSFER, src_channel=IBC_1_CHANNEL)
+        c, chain=IBC_1, port=TRANSFER, channel=IBC_1_CHANNEL)
 
     assert (len(unreceived) == 0), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-acks ibc-0 ibc-1 transfer channel-1
+    # hermes query packet unreceived-acks ibc-1 transfer channel-1
     unreceived = packet.query_unreceived_acks(
-        c, src=IBC_1, dst=IBC_0, src_port=TRANSFER, src_channel=IBC_1_CHANNEL)
+        c, chain=IBC_1, port=TRANSFER, channel=IBC_1_CHANNEL)
 
     assert (len(unreceived) == 0), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-packets ibc-1 ibc-0 transfer channel-0
+    # hermes query packet unreceived-packets ibc-0 transfer channel-0
     unreceived = packet.query_unreceived_packets(
-        c, src=IBC_0, dst=IBC_1, src_port=TRANSFER, src_channel=IBC_0_CHANNEL)
+        c, chain=IBC_0, port=TRANSFER, channel=IBC_0_CHANNEL)
 
     assert (len(unreceived) == 0), (unreceived, "unreceived packet mismatch")
 
-    # hermes query packet unreceived-acks ibc-1 ibc-0 transfer channel-0
+    # hermes query packet unreceived-acks ibc-0 transfer channel-0
     unreceived = packet.query_unreceived_acks(
-        c, src=IBC_0, dst=IBC_1, src_port=TRANSFER, src_channel=IBC_0_CHANNEL)
+        c, chain=IBC_0, port=TRANSFER, channel=IBC_0_CHANNEL)
 
     assert (len(unreceived) == 0), (unreceived, "unreceived packet mismatch")
 

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.2.0`.
+Current version: `0.3.0`.
 
 The version of this guide is aligned with the [versioning of the ibc crates](../README.md).
 

guide/src/SUMMARY.md

@@ -1,6 +1,6 @@
 # Summary
 
-# Hermes (v0.2.0)
+# Hermes (v0.3.0)
 
 ---
 - [Introduction](./index.md)
@@ -29,11 +29,11 @@
 - [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)
+   - [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)
+   - [Packet relaying](./commands/relaying.md)
    - [Listen mode](./commands/listen/index.md)
    - [Client upgrade](./commands/upgrade/index.md)
      - [Testing client upgrade](./commands/upgrade/test.md)

guide/src/commands/global.md

@@ -1,9 +1,9 @@
 # Global options
 
-The Hermes accepts global options which affect all commands.
+Hermes accepts global options which affect all commands.
 
 ```shell
-hermes 0.2.0
+hermes 0.3.0
 Informal Systems <hello@informal.systems>
 Implementation of `hermes`, an IBC Relayer developed in Rust.
 

guide/src/commands/index.md

@@ -8,9 +8,13 @@ The `Commands` section presents the commands current available in Hermes
 
 Commands to manage keys (private keys) for each chain.
 
-**[Path Setup and Streaming](./setup-and-relaying/index.md)**
+**[Path Setup](./path-setup/index.md)**
 
-Commands to manage clients, connections, channels and performing packet relaying
+Commands to manage clients, connections, channels.
+
+**[Packet Relaying](./relaying.md)**
+
+Commands to start the relayer and relay packets.
 
 **[Listen Mode](./listen/index.md)**
 

guide/src/commands/misbehaviour/index.md

@@ -90,8 +90,8 @@ hermes query client state ibc-0 07-tendermint-0 | jq
 ```json
 {
   "result": {
-    "allow_update_after_expiry": false,
-    "allow_update_after_misbehaviour": false,
+    "allow_update_after_expiry": true,
+    "allow_update_after_misbehaviour": true,
     "chain_id": "ibc-1",
     "frozen_height": {
       "revision_height": 16,

guide/src/commands/setup-and-relaying/clients.md → guide/src/commands/path-setup/clients.md

@@ -29,15 +29,20 @@ hermes create client ibc-0 ibc-1
 ```
 
 ```rust
-Success: CreateClient(
     CreateClient(
         Attributes {
-            height: Height { revision: 0, height: 264 },
+            height: Height {
+                revision: 0,
+                height: 286,
+            },
             client_id: ClientId(
-                "07-tendermint-1",
+                "07-tendermint-0",
             ),
             client_type: Tendermint,
-            consensus_height: Height { revision: 1, height: 253 },
+            consensus_height: Height {
+                revision: 1,
+                height: 274,
+            },
         },
     ),
 )
@@ -86,7 +91,9 @@ Success: UpdateClient(
             consensus_height: Height { revision: 1, height: 293 },
         },
         header: Some(
-            Tendermint(...),
+            Tendermint(
+                 Header {...},
+            ),
         ),
     },
 )
@@ -112,7 +119,9 @@ Success: UpdateClient(
             consensus_height: Height { revision: 1, height: 320 },
         },
         header: Some(
-            Tendermint(...),
+            Tendermint(
+                 Header {...},
+            ),
         ),
     },
 )

guide/src/commands/setup-and-relaying/connections.md → guide/src/commands/path-setup/connections.md

@@ -194,4 +194,4 @@ Success: Connection {
 
 ## 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](./packets.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.md#packet-delay) and the [connection delay specification](https://github.com/cosmos/ibc/tree/master/spec/core/ics-003-connection-semantics).

guide/src/commands/setup-and-relaying/index.md → guide/src/commands/path-setup/index.md

@@ -1,17 +1,16 @@
-# Path Setup and Relay Commands
+# Path Setup
 
-This section describes a number of commands that can be used to manage clients, connections, channels and relay over new or existing  paths.
+This section describes a number of commands that can be used to manage clients, connections, channels.
 
 | CLI name               | Description                                                                                                     |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------- |
 | `create client`        | [Create a client for source chain on destination chain](./clients.md#create-client)                         |
 | `update client`        | [Update the specified client on destination chain](./clients.md#md-client)                              |
 | `create connection`    | [Establish a connection using existing or new clients](./connections.md#establish-connection)                            |
 | `create channel`       | [Establish a channel using existing or new connection](./channels.md#establish-channel)                            |
-| `start`                | [Relay packets over a new or exsiting channel](./packets.md#start)                            |
 
 
-## Create 
+## Create
 Use the `create` commands to create a new clients, connections and channels.
 
 ```shell
@@ -28,21 +27,17 @@ SUBCOMMANDS:
     channel    Create a new channel between two chains
 ```
 
-## Relay 
-Use the `start` commands to start relaying packets over one path.
+## Update
+Use the `update` commands to update a client.
 
 ```shell
 USAGE:
-    hermes start <OPTIONS>
+    hermes update <SUBCOMMAND>
 
 DESCRIPTION:
-    Start the relayer
+    Update objects (clients) on chains
 
-POSITIONAL ARGUMENTS:
-    src_chain_id              identifier of the source chain
-    dst_chain_id              identifier of the destination chain
-
-FLAGS:
-    -p, --src-port-id SRC-PORT-ID
-    -c, --src-channel-id SRC-CHANNEL-ID
-```
+SUBCOMMANDS:
+    help       Get usage information
+    client     Update an IBC client
+```

guide/src/commands/queries/client.md

@@ -102,8 +102,8 @@ Success: ClientState {
         "upgrade",
         "upgradedIBCState",
     ],
-    allow_update_after_expiry: false,
-    allow_update_after_misbehaviour: false,
+    allow_update_after_expiry: true,
+    allow_update_after_misbehaviour: true,
 }
 ```