Skip to content

Commit b540b42

Browse files
romacandynogebuchmanancazamfiradizere
authored
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>
1 parent 70a5f01 commit b540b42

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

92 files changed

+6225
-1000
lines changed

‎.github/workflows/guide.yml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: deploy
2+
3+
on:
4+
push:
5+
branches:
6+
- andy/docs
7+
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-20.04
11+
steps:
12+
- uses: actions/checkout@v2
13+
14+
- name: Setup mdBook
15+
uses: peaceiris/actions-mdbook@v1
16+
with:
17+
mdbook-version: "0.4.6"
18+
19+
- name: Setup mdBook-mermaid
20+
uses: actions-rs/cargo@v1
21+
with:
22+
command: install
23+
args: mdbook-mermaid
24+
25+
- run: |
26+
cd guide
27+
mdbook build
28+
- name: Deploy
29+
uses: peaceiris/actions-gh-pages@v3
30+
with:
31+
github_token: ${{ secrets.GITHUB_TOKEN }}
32+
publish_dir: ./guide/book

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
- Implement command to perform the handshake for a new channel ([#557])
1717
- Query all connections command ([#553])
1818
- Query all channels command ([#568])
19+
- Added a relayer binary guide ([#542])
20+
- Split the dev-env script in `setup_chains` and `init_clients` ([#577])
1921

2022
- [relayer]
2123
- Added retry mechanism, restructured relayer ([#519])
@@ -76,12 +78,14 @@
7678
[#537]: https://github.com/informalsystems/ibc-rs/issues/537
7779
[#538]: https://github.com/informalsystems/ibc-rs/issues/538
7880
[#540]: https://github.com/informalsystems/ibc-rs/issues/540
81+
[#542]: https://github.com/informalsystems/ibc-rs/issues/542
7982
[#555]: https://github.com/informalsystems/ibc-rs/issues/555
8083
[#554]: https://github.com/informalsystems/ibc-rs/issues/554
8184
[#553]: https://github.com/informalsystems/ibc-rs/issues/553
8285
[#557]: https://github.com/informalsystems/ibc-rs/issues/557
8386
[#563]: https://github.com/informalsystems/ibc-rs/issues/563
8487
[#568]: https://github.com/informalsystems/ibc-rs/issues/568
88+
[#577]: https://github.com/informalsystems/ibc-rs/issues/577
8589
[#582]: https://github.com/informalsystems/ibc-rs/issues/582
8690
[#583]: https://github.com/informalsystems/ibc-rs/issues/583
8791
[#590]: https://github.com/informalsystems/ibc-rs/issues/590

‎README.md

+31-21
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,39 @@
88

99
Rust implementation of the Inter-Blockchain Communication (IBC) protocol.
1010

11-
This project consists of the following crates:
11+
This project comprises primarily four crates:
1212

13-
- The [`ibc`](https://docs.rs/ibc) crate defines the main data structures and on-chain logic for the IBC protocol.
14-
- The [`ibc-relayer`](https://docs.rs/ibc-relayer) crate provides an implementation of an IBC relayer, as a library.
15-
- [`hermes`](https://hermes.informal.systems) is a command-line interface for the IBC relayer provided by this project.
16-
17-
See the table below for details.
13+
- The [`ibc`][ibc-crate-link] crate defines the main data structures and
14+
on-chain logic for the IBC protocol.
15+
- The [`ibc-relayer`][relayer-crate-link] crate provides an implementation
16+
of an IBC relayer, as a _library_.
17+
- The [`ibc-relayer-cli`][relayer-cli-crate-link] is a CLI (a wrapper
18+
over the `ibc-relayer` library), comprising the
19+
[`hermes`](https://hermes.informal.systems) binary.
20+
- The [`ibc-proto`][ibc-proto-crate-link] is a library with proto definitions
21+
necessary for interacting with Cosmos SDK
22+
[IBC structs](https://github.com/cosmos/cosmos-sdk/tree/master/proto/ibc).
23+
24+
See the table below for more details.
1825

1926
Includes [TLA+ specifications](/docs/spec).
2027

21-
> TODO: update the crate and docs links below (for relayer and relayer-cli).
22-
2328
| Crate name | Type | Version | Docs |
2429
|:-------------:|:------:|:-------------:|:-----:|
25-
| [ibc (modules)](./modules) | lib| [![IBC Crate][ibc-crate-image]][ibc-crate-link] | [![Docs][ibc-docs-image]][ibc-docs-link] |
26-
| [ibc-relayer](./relayer) | lib | [![Relayer Crate][relayer-crate-image]][relayer-crate-link] | [![Docs][relayer-docs-image]][relayer-docs-link] |
27-
| [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] |
30+
| [ibc](./modules) (modules) | lib| [![IBC Crate][ibc-crate-image]][ibc-crate-link] | [![IBC Docs][ibc-docs-image]][ibc-docs-link] |
31+
| [ibc-relayer](./relayer) | lib | [![IBC Relayer Crate][relayer-crate-image]][relayer-crate-link] | [![IBC Relayer Docs][relayer-docs-image]][relayer-docs-link] |
32+
| [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] |
33+
| [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] |
2834

2935

3036
## Requirements
3137

3238
Developed with the latest stable version of Rust: `1.49.0`.
3339
(May work with older versions.)
3440

35-
## Relayer guide
41+
## Hermes Guide
3642

37-
The main relayer CLI binary, called `hermes`, has a comprehensive guide at
43+
The relayer CLI binary, called `hermes`, has a comprehensive guide at
3844
[hermes.informal.systems](http://hermes.informal.systems).
3945

4046
## Contributing
@@ -74,14 +80,18 @@ Unless required by applicable law or agreed to in writing, software distributed
7480
[ibc-crate-link]: https://crates.io/crates/ibc
7581
[ibc-docs-image]: https://docs.rs/ibc/badge.svg
7682
[ibc-docs-link]: https://docs.rs/ibc/
77-
[relayer-crate-image]: https://img.shields.io/crates/v/ibc.svg
78-
[relayer-crate-link]: https://crates.io/crates/ibc
79-
[relayer-docs-image]: https://docs.rs/ibc/badge.svg
80-
[relayer-docs-link]: https://docs.rs/ibc/
81-
[relayer-cli-crate-image]: https://img.shields.io/crates/v/ibc.svg
82-
[relayer-cli-crate-link]: https://crates.io/crates/ibc
83-
[relayer-cli-docs-image]: https://docs.rs/ibc/badge.svg
84-
[relayer-cli-docs-link]: https://docs.rs/ibc/
83+
[relayer-crate-image]: https://img.shields.io/crates/v/ibc-relayer.svg
84+
[relayer-crate-link]: https://crates.io/crates/ibc-relayer
85+
[relayer-docs-image]: https://docs.rs/ibc-relayer/badge.svg
86+
[relayer-docs-link]: https://docs.rs/ibc-relayer/
87+
[relayer-cli-crate-image]: https://img.shields.io/crates/v/ibc-relayer-cli.svg
88+
[relayer-cli-crate-link]: https://crates.io/crates/ibc-relayer-cli
89+
[relayer-cli-docs-image]: https://docs.rs/ibc-relayer-cli/badge.svg
90+
[relayer-cli-docs-link]: https://docs.rs/ibc-relayer-cli/
91+
[ibc-proto-crate-image]: https://img.shields.io/crates/v/ibc-proto.svg
92+
[ibc-proto-crate-link]: https://crates.io/crates/ibc-proto
93+
[ibc-proto-docs-image]: https://docs.rs/ibc-proto/badge.svg
94+
[ibc-proto-docs-link]: https://docs.rs/ibc-proto/
8595

8696
[build-image]: https://github.com/informalsystems/ibc-rs/workflows/Rust/badge.svg
8797
[build-link]: https://github.com/informalsystems/ibc-rs/actions?query=workflow%3ARust

‎config.toml

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
[global]
2+
timeout = '10s'
3+
strategy = 'naive'
4+
log_level = 'error'
5+
6+
[[chains]]
7+
id = 'ibc-0'
8+
rpc_addr = 'tcp://localhost:26657'
9+
grpc_addr = 'tcp://localhost:9090'
10+
account_prefix = 'cosmos'
11+
key_name = 'testkey'
12+
store_prefix = 'ibc'
13+
gas = 200000
14+
clock_drift = '5s'
15+
trusting_period = '14days'
16+
17+
[chains.trust_threshold]
18+
numerator = '1'
19+
denominator = '3'
20+
21+
[chains.peers]
22+
primary = '8CE3551ABF73A754A7BC6BA32553E82D5526313C'
23+
24+
[[chains.peers.light_clients]]
25+
peer_id = '8CE3551ABF73A754A7BC6BA32553E82D5526313C'
26+
address = 'tcp://localhost:26657'
27+
timeout = '10s'
28+
trusted_header_hash = '51E5C6F24D7F0E249624C8D31099720D316198DBEB1FA877428A0406248DBDB8'
29+
trusted_height = '40'
30+
31+
[chains.peers.light_clients.store]
32+
type = 'disk'
33+
path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-0/data/8CE3551ABF73A754A7BC6BA32553E82D5526313C'
34+
35+
[[chains.peers.light_clients]]
36+
peer_id = '2427F8D914A6862279B3326FA64F76E3BC06DB2E'
37+
address = 'tcp://localhost:26657'
38+
timeout = '10s'
39+
trusted_header_hash = '51E5C6F24D7F0E249624C8D31099720D316198DBEB1FA877428A0406248DBDB8'
40+
trusted_height = '40'
41+
42+
[chains.peers.light_clients.store]
43+
type = 'disk'
44+
path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-0/data/2427F8D914A6862279B3326FA64F76E3BC06DB2E'
45+
46+
[[chains]]
47+
id = 'ibc-1'
48+
rpc_addr = 'tcp://localhost:26557'
49+
grpc_addr = 'tcp://localhost:9091'
50+
account_prefix = 'cosmos'
51+
key_name = 'testkey'
52+
store_prefix = 'ibc'
53+
gas = 200000
54+
clock_drift = '5s'
55+
trusting_period = '14days'
56+
57+
[chains.trust_threshold]
58+
numerator = '1'
59+
denominator = '3'
60+
61+
[chains.peers]
62+
primary = 'D7F25416D5156D76C05C7592EC1C97962EA696F9'
63+
64+
[[chains.peers.light_clients]]
65+
peer_id = 'D7F25416D5156D76C05C7592EC1C97962EA696F9'
66+
address = 'tcp://localhost:26557'
67+
timeout = '10s'
68+
trusted_header_hash = 'DF6AB9F99C0B0E99DCE299566E92082E6611F0588F10ED3630CE41B245093526'
69+
trusted_height = '30'
70+
71+
[chains.peers.light_clients.store]
72+
type = 'disk'
73+
path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-1/data/D7F25416D5156D76C05C7592EC1C97962EA696F9'
74+
75+
[[chains.peers.light_clients]]
76+
peer_id = 'A885BB3D3DFF6101188B462466AE926E7A6CD51E'
77+
address = 'tcp://localhost:26557'
78+
timeout = '10s'
79+
trusted_header_hash = '0C915453C65A32A557C9D5CCF905ACBFC06D95AA780D069C0E0B28C0D433346A'
80+
trusted_height = '31'
81+
82+
[chains.peers.light_clients.store]
83+
type = 'disk'
84+
path = '/Users/coromac/Informal/Code/Current/ibc-rs/data/ibc-1/data/A885BB3D3DFF6101188B462466AE926E7A6CD51E'
85+
86+
[[connections]]
87+
a_chain = 'ibc-0'
88+
b_chain = 'ibc-1'
89+
90+
[[connections.paths]]
91+
a_port = 'transfer'
92+
b_port = 'transfer'

‎config_example.toml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[global]
2+
timeout = '10s'
3+
strategy = 'naive'
4+
log_level = 'error'
5+
6+
[[chains]]
7+
id = 'ibc-0'
8+
rpc_addr = 'tcp://localhost:26657'
9+
grpc_addr = 'tcp://localhost:9090'
10+
account_prefix = 'cosmos'
11+
key_name = 'testkey'
12+
store_prefix = 'ibc'
13+
gas = 3000000
14+
clock_drift = '5s'
15+
trusting_period = '14days'
16+
17+
[chains.trust_threshold]
18+
numerator = '1'
19+
denominator = '3'
20+
21+
[[chains]]
22+
id = 'ibc-1'
23+
rpc_addr = 'tcp://localhost:26557'
24+
grpc_addr = 'tcp://localhost:9091'
25+
account_prefix = 'cosmos'
26+
key_name = 'testkey'
27+
store_prefix = 'ibc'
28+
gas = 3000000
29+
clock_drift = '5s'
30+
trusting_period = '14days'
31+
32+
[chains.trust_threshold]
33+
numerator = '1'
34+
denominator = '3'
35+
36+
[[connections]]
37+
a_chain = 'ibc-0'
38+
b_chain = 'ibc-1'
39+
40+
[[connections.paths]]
41+
a_port = 'transfer'
42+
b_port = 'transfer'

0 commit comments

Comments
 (0)