Relayer documentation (informalsystems#589)

* Initial documentation using mdbook (informalsystems#542)

* Added README page to the guide with instructions. Fix index page (informalsystems#542)

* Added more content mostly in the configuration section (informalsystems#542)

* Some cleaning up and adding some placeholder content to a few pages (informalsystems#542)

* Added information to the index page (informalsystems#542)

* Added more content, new sections (most under in transactions), added glossary (informalsystems#542)

* Added info to light client page, additional theme change and some structure refactor (informalsystems#542)

* Added content for keys. Updated some commands references. (informalsystems#542)

* Added tutorial section. Breakdown tutorial (informalsystems#542)

* More content to tutorial (informalsystems#542)

* Adding more content to tutorial (informalsystems#542)

* Update relay_packets.md

* Adding more content, fixing content mostly in local chains file (informalsystems#542)

* Fixing some content to show hermes (informalsystems#542)

* Added content to the create-client section (informalsystems#452)

* Review sections 1-3

* Revew 3.1, remove loop_config, add config_example.toml

* Small layout change

* fix CLI examples

* fixed and clarified ID parameters

* Format bytearrays as hex-encoded strings in various commands

* Formatting

* Added 4.3.1 and 4.5.1

* fix query client doc

* fix query client connections doc

* Add the relayer_loop doc

* Add documentation for tx raw connection commands and change from positional arguments to flags

* Avoid duplicate tag name for ConnectionEnd, ChannelEnd, AnyConsensusState and AnyClientState

* Fix JSON output in `tx raw` connection guide

* Update guide following 1ed6147

* Remove tags on ChannelEnd and ConnectionEnd

* Add documentation for query connection commands

* json for client commands, fix in relayer loop doc

* Add documentation for query channel(s) commands

* Improve output of Python script a bit

* Adding guide build CI workflow (informalsystems#542)

* tx packet section, changed packet-send to ft-transfer

* Some css changes to better show few things (informalsystems#542)

* formatting

* Work around gumdrop limitation which cuts off flags help text if too long

* Add documentation for tx raw chan-* commands

* Fix typo in e2e Python script

* Adapt e2e script to new flags of tx conn commands

* Add stub doc for tx raw chan-close-* commands

* Fix typo

* Improve tx raw conn-* doc

* Improve tx raw chan-open-* doc

* Only return a single result from Output type, to avoid unnecessary brackets in JSON output

* Add diagrams to tx channel and tx connection pages

* packet query docs

* starting on feature summary

* Fix typo

* Adapt mermaid theme to mdbook theme

* Add chan-close results to doc and to e2e script (disabled for now)

* Rename events to listen mode and add listen command

* File to support custom domain (informalsystems#542)

* Fix mermaid theme detection

* Improve conn and chan diagrams

* Adding step to install mdbook-mermaid (informalsystems#542)

* Adding step to install mdbook-mermaid on CI (informalsystems#542)

* Removing full path from config example (informalsystems#542)

* Remove log statement

* Fixing type in guide.yml (informalsystems#542)

* renamed troubleshoot [test]

* Look for default config in ~/.hermes/config.toml and update guide

* Minor stylistic change

* Added Help

* Split dev-env script into setup-chains and init-clients

* Breakdown of the relay packets into separate sections (informalsystems#542)

* Fixed links in help.md

* Formatting

* Fixing color for navigation buttons in mobile display (informalsystems#542)

* Fix gaia version (informalsystems#542)

* Added pre-requisite (Golang) needed for gaia (informalsystems#542)

* Adding more content to the local_chains page (informalsystems#542)

* remove order flag from tx chan clis

* Add high level content in transactions

* add clarification on identifiers and start cleaning 4.1.3 subsections

* restructure tutorial

* add relay path tutorial

* Finish the channel close handshake commands referrence

* remove forgotten wip

* Move chan-close commands to their own section

* Remove duplicate content

* Moved miscellaneous into help. Consolidated the help section.

* review 1-3

* Add section to install hermes via cargo install

* Rename Setup page to Installation

* Patching gaia

* features and matrix

* Add [[connections]] section to config.toml

* Whitespace

* Touch up feature matrix a bit

* small nits

* Uppercase feature descriptions

* typo fix and added link

* merge features in a new column in matrix, fix a few entries

* cleanup

* formatting

* Index nits

* Getting started, prereq

* Fixed hyperlinks to installation.md

* remove the operation instructions

* Fixed tutorial URLS

* Fixed URLS in commands and local_chains.md

* Queries overview

* Relayer CLI readme stripped down to essentials

* changelog

* review up to 5.2

* review  5.3

* review  5.4

* finish 5 review

* Add instructions for running two relayers for bidirectional relaying

* Fix broken links found with mdbook-linkcheck

* Check for broken links on CI

* Revert "Check for broken links on CI"

This reverts commit c4f8509.

* Main readme. Some fixes

* Fix typo

* Hermes <> IBC Relayer CLI

* Fix a couple more typos

* Unify Transactions and Queries index pages

* Remove $ prefix in front of commands for easier copy-paste

* fix concurrent packet relay section

* Update title of two paths page

* Disambiguation Hermes<>CLI

* More explanation re: CLI

* Nit in readme

* Casing and descriptions

* More casing

* Formatting

* Consistent casing in sidebar

* nits

* Unify notes

* Nitpick

* Minor stuff

Co-authored-by: Andy Nogueira <me@andynogueira.dev>
Co-authored-by: Ethan Buchman <ethan@coinculture.info>
Co-authored-by: Anca Zamfir <zamfiranca@gmail.com>
Co-authored-by: Adi Seredinschi <adi@informal.systems>

.github/workflows/guide.yml

@@ -0,0 +1,32 @@
+name: deploy
+
+on:
+  push:
+    branches:
+      - andy/docs
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "0.4.6"
+
+      - name: Setup mdBook-mermaid
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: mdbook-mermaid
+
+      - run: |
+          cd guide
+          mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./guide/book

CHANGELOG.md

@@ -16,6 +16,8 @@
   - Implement command to perform the handshake for a new channel ([#557])
   - Query all connections command ([#553])
   - Query all channels command ([#568])
+  - Added a relayer binary guide ([#542])
+  - Split the dev-env script in `setup_chains` and `init_clients` ([#577])
 
 - [relayer]
   - Added retry mechanism, restructured relayer ([#519])
@@ -76,12 +78,14 @@
 [#537]: https://github.com/informalsystems/ibc-rs/issues/537
 [#538]: https://github.com/informalsystems/ibc-rs/issues/538
 [#540]: https://github.com/informalsystems/ibc-rs/issues/540
+[#542]: https://github.com/informalsystems/ibc-rs/issues/542
 [#555]: https://github.com/informalsystems/ibc-rs/issues/555
 [#554]: https://github.com/informalsystems/ibc-rs/issues/554
 [#553]: https://github.com/informalsystems/ibc-rs/issues/553
 [#557]: https://github.com/informalsystems/ibc-rs/issues/557
 [#563]: https://github.com/informalsystems/ibc-rs/issues/563
 [#568]: https://github.com/informalsystems/ibc-rs/issues/568
+[#577]: https://github.com/informalsystems/ibc-rs/issues/577
 [#582]: https://github.com/informalsystems/ibc-rs/issues/582
 [#583]: https://github.com/informalsystems/ibc-rs/issues/583
 [#590]: https://github.com/informalsystems/ibc-rs/issues/590

README.md

@@ -8,33 +8,39 @@
 
 Rust implementation of the Inter-Blockchain Communication (IBC) protocol.
 
-This project consists of the following crates:
+This project comprises primarily four crates:
 
- - The [`ibc`](https://docs.rs/ibc) crate defines the main data structures and on-chain logic  for the IBC protocol.
-- The [`ibc-relayer`](https://docs.rs/ibc-relayer) crate provides an implementation of an IBC relayer, as a library.
-- [`hermes`](https://hermes.informal.systems) is a command-line interface for the IBC relayer provided by this project.
-
-See the table below for details.
+- The [`ibc`][ibc-crate-link] crate defines the main data structures and 
+  on-chain logic for the IBC protocol.
+- The [`ibc-relayer`][relayer-crate-link] crate provides an implementation 
+  of an IBC relayer, as a _library_.
+- The [`ibc-relayer-cli`][relayer-cli-crate-link] is a CLI (a wrapper 
+  over the `ibc-relayer` library), comprising the 
+  [`hermes`](https://hermes.informal.systems) binary.
+- The [`ibc-proto`][ibc-proto-crate-link] is a library with proto definitions 
+  necessary for interacting with Cosmos SDK
+  [IBC structs](https://github.com/cosmos/cosmos-sdk/tree/master/proto/ibc).
+
+See the table below for more details.
 
 Includes [TLA+ specifications](/docs/spec).
 
-> TODO: update the crate and docs links below (for relayer and relayer-cli).
-
 | Crate name    |   Type   |     Version       | Docs   |
 |:-------------:|:------:|:-------------:|:-----:|
-| [ibc (modules)](./modules) | lib|  [![IBC Crate][ibc-crate-image]][ibc-crate-link] | [![Docs][ibc-docs-image]][ibc-docs-link] |
-| [ibc-relayer](./relayer)      | lib |  [![Relayer Crate][relayer-crate-image]][relayer-crate-link]  | [![Docs][relayer-docs-image]][relayer-docs-link] |
-| [ibc-relayer-cli](./relayer-cli)  | bin: [hermes](relayer-cli/) |  [![Relayer CLI Crate][relayer-cli-crate-image]][relayer-cli-crate-link]      |  [![Docs][relayer-cli-docs-image]][relayer-cli-docs-link] |
+| [ibc](./modules) (modules) | lib|  [![IBC Crate][ibc-crate-image]][ibc-crate-link] | [![IBC Docs][ibc-docs-image]][ibc-docs-link] |
+| [ibc-relayer](./relayer)      | lib |  [![IBC Relayer Crate][relayer-crate-image]][relayer-crate-link]  | [![IBC Relayer Docs][relayer-docs-image]][relayer-docs-link] |
+| [ibc-relayer-cli](./relayer-cli)  | bin: [hermes](relayer-cli/) |  [![IBC Relayer CLI Crate][relayer-cli-crate-image]][relayer-cli-crate-link]      |  [![IBC Relayer CLI Docs][relayer-cli-docs-image]][relayer-cli-docs-link] |
+| [ibc-proto](./proto)  | lib |  [![IBC Proto Crate][ibc-proto-crate-image]][ibc-proto-crate-link]      |  [![IBC Proto Docs][ibc-proto-docs-image]][ibc-proto-docs-link] |
 
 
 ## Requirements 
 
 Developed with the latest stable version of Rust: `1.49.0`. 
 (May work with older versions.)
 
-## Relayer guide
+## Hermes Guide
 
-The main relayer CLI binary, called `hermes`, has a comprehensive guide at
+The relayer CLI binary, called `hermes`, has a comprehensive guide at
 [hermes.informal.systems](http://hermes.informal.systems).
 
 ## Contributing
@@ -74,14 +80,18 @@ Unless required by applicable law or agreed to in writing, software distributed
 [ibc-crate-link]: https://crates.io/crates/ibc
 [ibc-docs-image]: https://docs.rs/ibc/badge.svg
 [ibc-docs-link]: https://docs.rs/ibc/
-[relayer-crate-image]: https://img.shields.io/crates/v/ibc.svg
-[relayer-crate-link]: https://crates.io/crates/ibc
-[relayer-docs-image]: https://docs.rs/ibc/badge.svg
-[relayer-docs-link]: https://docs.rs/ibc/
-[relayer-cli-crate-image]: https://img.shields.io/crates/v/ibc.svg
-[relayer-cli-crate-link]: https://crates.io/crates/ibc
-[relayer-cli-docs-image]: https://docs.rs/ibc/badge.svg
-[relayer-cli-docs-link]: https://docs.rs/ibc/
+[relayer-crate-image]: https://img.shields.io/crates/v/ibc-relayer.svg
+[relayer-crate-link]: https://crates.io/crates/ibc-relayer
+[relayer-docs-image]: https://docs.rs/ibc-relayer/badge.svg
+[relayer-docs-link]: https://docs.rs/ibc-relayer/
+[relayer-cli-crate-image]: https://img.shields.io/crates/v/ibc-relayer-cli.svg
+[relayer-cli-crate-link]: https://crates.io/crates/ibc-relayer-cli
+[relayer-cli-docs-image]: https://docs.rs/ibc-relayer-cli/badge.svg
+[relayer-cli-docs-link]: https://docs.rs/ibc-relayer-cli/
+[ibc-proto-crate-image]: https://img.shields.io/crates/v/ibc-proto.svg
+[ibc-proto-crate-link]: https://crates.io/crates/ibc-proto
+[ibc-proto-docs-image]: https://docs.rs/ibc-proto/badge.svg
+[ibc-proto-docs-link]: https://docs.rs/ibc-proto/
 
 [build-image]: https://github.com/informalsystems/ibc-rs/workflows/Rust/badge.svg
 [build-link]: https://github.com/informalsystems/ibc-rs/actions?query=workflow%3ARust

config.toml

@@ -0,0 +1,92 @@
+[global]
+timeout = '10s'
+strategy = 'naive'
+log_level = 'error'
+
+[[chains]]
+id = 'ibc-0'
+rpc_addr = 'tcp://localhost:26657'
+grpc_addr = 'tcp://localhost:9090'
+account_prefix = 'cosmos'
+key_name = 'testkey'
+store_prefix = 'ibc'
+gas = 200000
+clock_drift = '5s'
+trusting_period = '14days'
+
+[chains.trust_threshold]
+numerator = '1'
+denominator = '3'
+
+[chains.peers]
+primary = '8CE3551ABF73A754A7BC6BA32553E82D5526313C'
+
+[[chains.peers.light_clients]]
+peer_id = '8CE3551ABF73A754A7BC6BA32553E82D5526313C'
+address = 'tcp://localhost:26657'
+timeout = '10s'
+trusted_header_hash = '51E5C6F24D7F0E249624C8D31099720D316198DBEB1FA877428A0406248DBDB8'
+trusted_height = '40'
+
+[chains.peers.light_clients.store]
+type = 'disk'
+path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-0/data/8CE3551ABF73A754A7BC6BA32553E82D5526313C'
+
+[[chains.peers.light_clients]]
+peer_id = '2427F8D914A6862279B3326FA64F76E3BC06DB2E'
+address = 'tcp://localhost:26657'
+timeout = '10s'
+trusted_header_hash = '51E5C6F24D7F0E249624C8D31099720D316198DBEB1FA877428A0406248DBDB8'
+trusted_height = '40'
+
+[chains.peers.light_clients.store]
+type = 'disk'
+path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-0/data/2427F8D914A6862279B3326FA64F76E3BC06DB2E'
+
+[[chains]]
+id = 'ibc-1'
+rpc_addr = 'tcp://localhost:26557'
+grpc_addr = 'tcp://localhost:9091'
+account_prefix = 'cosmos'
+key_name = 'testkey'
+store_prefix = 'ibc'
+gas = 200000
+clock_drift = '5s'
+trusting_period = '14days'
+
+[chains.trust_threshold]
+numerator = '1'
+denominator = '3'
+
+[chains.peers]
+primary = 'D7F25416D5156D76C05C7592EC1C97962EA696F9'
+
+[[chains.peers.light_clients]]
+peer_id = 'D7F25416D5156D76C05C7592EC1C97962EA696F9'
+address = 'tcp://localhost:26557'
+timeout = '10s'
+trusted_header_hash = 'DF6AB9F99C0B0E99DCE299566E92082E6611F0588F10ED3630CE41B245093526'
+trusted_height = '30'
+
+[chains.peers.light_clients.store]
+type = 'disk'
+path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-1/data/D7F25416D5156D76C05C7592EC1C97962EA696F9'
+
+[[chains.peers.light_clients]]
+peer_id = 'A885BB3D3DFF6101188B462466AE926E7A6CD51E'
+address = 'tcp://localhost:26557'
+timeout = '10s'
+trusted_header_hash = '0C915453C65A32A557C9D5CCF905ACBFC06D95AA780D069C0E0B28C0D433346A'
+trusted_height = '31'
+
+[chains.peers.light_clients.store]
+type = 'disk'
+path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-1/data/A885BB3D3DFF6101188B462466AE926E7A6CD51E'
+
+[[connections]]
+a_chain = 'ibc-0'
+b_chain = 'ibc-1'
+
+[[connections.paths]]
+a_port = 'transfer'
+b_port = 'transfer'

config_example.toml

@@ -0,0 +1,42 @@
+[global]
+timeout = '10s'
+strategy = 'naive'
+log_level = 'error'
+
+[[chains]]
+id = 'ibc-0'
+rpc_addr = 'tcp://localhost:26657'
+grpc_addr = 'tcp://localhost:9090'
+account_prefix = 'cosmos'
+key_name = 'testkey'
+store_prefix = 'ibc'
+gas = 3000000
+clock_drift = '5s'
+trusting_period = '14days'
+
+[chains.trust_threshold]
+numerator = '1'
+denominator = '3'
+
+[[chains]]
+id = 'ibc-1'
+rpc_addr = 'tcp://localhost:26557'
+grpc_addr = 'tcp://localhost:9091'
+account_prefix = 'cosmos'
+key_name = 'testkey'
+store_prefix = 'ibc'
+gas = 3000000
+clock_drift = '5s'
+trusting_period = '14days'
+
+[chains.trust_threshold]
+numerator = '1'
+denominator = '3'
+
+[[connections]]
+a_chain = 'ibc-0'
+b_chain = 'ibc-1'
+
+[[connections.paths]]
+a_port = 'transfer'
+b_port = 'transfer'