diff --git a/.github/workflows/guide.yml b/.github/workflows/guide.yml index 3ee6996edc..c5175afbee 100644 --- a/.github/workflows/guide.yml +++ b/.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: diff --git a/guide/README.md b/guide/README.md index 032b0025eb..86dac1fa5f 100644 --- a/guide/README.md +++ b/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`). diff --git a/guide/book.toml b/guide/book.toml index c11547b50c..4e4655b577 100644 --- a/guide/book.toml +++ b/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] + diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 3e1db45299..f448ea019e 100644 --- a/guide/src/SUMMARY.md +++ b/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) --- diff --git a/guide/src/features/matrix.md b/guide/src/advanced/features.md similarity index 62% rename from guide/src/features/matrix.md rename to guide/src/advanced/features.md index 38cf9a3add..245f19000e 100644 --- a/guide/src/features/matrix.md +++ b/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__: | `..__A` | building and sending `msg` from a command that scans chain state | | `..__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 diff --git a/guide/src/advanced/index.md b/guide/src/advanced/index.md new file mode 100644 index 0000000000..f715cc2aee --- /dev/null +++ b/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. \ No newline at end of file diff --git a/guide/src/advanced/troubleshooting/help-command.md b/guide/src/advanced/troubleshooting/help-command.md new file mode 100644 index 0000000000..74d39230a5 --- /dev/null +++ b/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 + +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-connection --a-port --b-port + + hermes create channel [OPTIONS] --a-chain --b-chain --a-port --b-port --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 + 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 + The channel ordering, valid options 'unordered' (default) and 'ordered' + + [default: ORDER_UNORDERED] + + --yes + Skip new_client_connection confirmation + +FLAGS: + --a-chain + Identifier of the side `a` chain for the new channel + + --a-connection + Identifier of the connection on chain `a` to use in creating the new channel + + [aliases: a-conn] + + --a-port + Identifier of the side `a` port for the new channel + + --b-chain + Identifier of the side `b` chain for the new channel + + --b-port + Identifier of the side `b` port for the new channel +``` + +Additionally, the `-h`/`--help` flags typical for CLI applications work on +all commands. diff --git a/guide/src/advanced/troubleshooting/index.md b/guide/src/advanced/troubleshooting/index.md new file mode 100644 index 0000000000..92d49088ed --- /dev/null +++ b/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 diff --git a/guide/src/advanced/troubleshooting/inspect.md b/guide/src/advanced/troubleshooting/inspect.md new file mode 100644 index 0000000000..3958cadf1c --- /dev/null +++ b/guide/src/advanced/troubleshooting/inspect.md @@ -0,0 +1,176 @@ +# Inspecting the relayer state + +To get some insight into the state of the relayer, +Hermes will react to a `SIGUSR1` signal by dumping its state to +the console, either in plain text form or as a JSON object if Hermes +was started with the `--json` option. + +To send a `SIGUSR1` signal to Hermes, look up its process ID (below PID) +and use the following command: + +```shell +kill -SIGUSR1 PID +``` + +Hermes will print some information about the workers which are currently running. + +For example, with three chains configured and one channel between each pair of chains: + +```text +INFO Dumping state (triggered by SIGUSR1) +INFO +INFO * Chains: ibc-0, ibc-1, ibc-2 +INFO * Client workers: +INFO - client::ibc-0->ibc-1:07-tendermint-0 (id: 5) +INFO - client::ibc-0->ibc-2:07-tendermint-0 (id: 9) +INFO - client::ibc-1->ibc-0:07-tendermint-0 (id: 1) +INFO - client::ibc-1->ibc-2:07-tendermint-1 (id: 11) +INFO - client::ibc-2->ibc-0:07-tendermint-1 (id: 3) +INFO - client::ibc-2->ibc-1:07-tendermint-1 (id: 7) +INFO * Packet workers: +INFO - packet::channel-0/transfer:ibc-0->ibc-1 (id: 2) +INFO - packet::channel-0/transfer:ibc-1->ibc-0 (id: 6) +INFO - packet::channel-0/transfer:ibc-2->ibc-0 (id: 10) +INFO - packet::channel-1/transfer:ibc-0->ibc-2 (id: 4) +INFO - packet::channel-1/transfer:ibc-1->ibc-2 (id: 8) +INFO - packet::channel-1/transfer:ibc-2->ibc-1 (id: 12) +``` + +or in JSON form (prettified): + +```json +{ + "timestamp": "Jul 12 17:04:37.244", + "level": "INFO", + "fields": { + "message": "Dumping state (triggered by SIGUSR1)" + } +} +{ + "chains": [ + "ibc-0", + "ibc-1", + "ibc-2" + ], + "workers": { + "Client": [ + { + "id": 5, + "object": { + "type": "Client", + "dst_chain_id": "ibc-1", + "dst_client_id": "07-tendermint-0", + "src_chain_id": "ibc-0" + } + }, + { + "id": 9, + "object": { + "type": "Client", + "dst_chain_id": "ibc-2", + "dst_client_id": "07-tendermint-0", + "src_chain_id": "ibc-0" + } + }, + { + "id": 1, + "object": { + "type": "Client", + "dst_chain_id": "ibc-0", + "dst_client_id": "07-tendermint-0", + "src_chain_id": "ibc-1" + } + }, + { + "id": 11, + "object": { + "type": "Client", + "dst_chain_id": "ibc-2", + "dst_client_id": "07-tendermint-1", + "src_chain_id": "ibc-1" + } + }, + { + "id": 3, + "object": { + "type": "Client", + "dst_chain_id": "ibc-0", + "dst_client_id": "07-tendermint-1", + "src_chain_id": "ibc-2" + } + }, + { + "id": 7, + "object": { + "type": "Client", + "dst_chain_id": "ibc-1", + "dst_client_id": "07-tendermint-1", + "src_chain_id": "ibc-2" + } + } + ], + "Packet": [ + { + "id": 2, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-1", + "src_chain_id": "ibc-0", + "src_channel_id": "channel-0", + "src_port_id": "transfer" + } + }, + { + "id": 6, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-0", + "src_chain_id": "ibc-1", + "src_channel_id": "channel-0", + "src_port_id": "transfer" + } + }, + { + "id": 10, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-0", + "src_chain_id": "ibc-2", + "src_channel_id": "channel-0", + "src_port_id": "transfer" + } + }, + { + "id": 4, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-2", + "src_chain_id": "ibc-0", + "src_channel_id": "channel-1", + "src_port_id": "transfer" + } + }, + { + "id": 8, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-2", + "src_chain_id": "ibc-1", + "src_channel_id": "channel-1", + "src_port_id": "transfer" + } + }, + { + "id": 12, + "object": { + "type": "Packet", + "dst_chain_id": "ibc-1", + "src_chain_id": "ibc-2", + "src_channel_id": "channel-1", + "src_port_id": "transfer" + } + } + ] + } +} +``` \ No newline at end of file diff --git a/guide/src/advanced/troubleshooting/log-level.md b/guide/src/advanced/troubleshooting/log-level.md new file mode 100644 index 0000000000..f43613abd6 --- /dev/null +++ b/guide/src/advanced/troubleshooting/log-level.md @@ -0,0 +1,107 @@ +# Parametrize the log level + +This section explains how to parametrize the log output level of `hermes`. + + +The relayer configuration file permits parametrization of output verbosity via the knob called `log_level`. +This file is loaded by default from `$HOME/.hermes/config.toml`, but can be overridden in all commands +with the `--config` flag, e.g. `hermes --config ./path/to/my/config.toml some command`. + +Relevant snippet: + +```toml +[global] +log_level = 'error' +``` + +Valid options for `log_level` are: 'error', 'warn', 'info', 'debug', 'trace'. +These levels correspond to the tracing subcomponent of the relayer-cli, +[see here](https://docs.rs/tracing-core/0.1.17/tracing_core/struct.Level.html). + +The relayer will _always_ print a last line summarizing the result of its +operation for queries or transactions. In addition to this last line, +arbitrary debug, info, or other outputs may be produced. + + +## Overriding the tracing filter using `RUST_LOG` + +For debugging purposes, we may want to inspect which RPC queries the relayer is making. +The relayer makes use of the `tendermint-rpc` library to issue RPC queries, but +the output of this library is by default turned off in order to keep the logs more +readable. + +Using the `RUST_LOG` environment variable, we can turn logging on for the +`tendermint-rpc` library, as follows: + +``` +RUST_LOG=tendermint-rpc=debug,info hermes start +``` + +Setting the `RUST_LOG` environment variable to `tendermint_rpc=debug,info` instructs +the relayer to set the log level of the `tendermint_rpc` crate to `debug` and otherwise +use the `info` log level. + +> **Note:** While the `tendermint-rpc` contains a dash in its name, the logging filter +> expects a module name, which can only contain alphanumeric characters and underscores, +> hence why the filter above is written `tendermint_rpc=debug`. + +**Example:** + +``` +❯ RUST_LOG=tendermint_rpc=debug,info hermes start +2022-02-24T14:32:14.039555Z INFO ThreadId(01) using default configuration from '/Users/coromac/.hermes/config.toml' +2022-02-24T14:32:14.043500Z INFO ThreadId(01) telemetry service running, exposing metrics at http://127.0.0.1:3001/metrics +2022-02-24T14:32:14.043542Z INFO ThreadId(01) [rest] address not configured, REST server disabled +2022-02-24T14:32:14.049759Z DEBUG ThreadId(01) Incoming response: { + "jsonrpc": "2.0", + "id": "143b4580-c49e-47c1-81b2-4e7090f6e762", + "result": { + "node_info": { + "protocol_version": { + "p2p": "8", + "block": "11", + "app": "0" + }, + "id": "73f9134539f9845cd253dc302e36d48ee4c0f32d", + "listen_addr": "tcp://0.0.0.0:27003", + "network": "ibc0", + "version": "v0.34.14", + "channels": "40202122233038606100", + "moniker": "ibc0", + "other": { + "tx_index": "on", + "rpc_address": "tcp://0.0.0.0:27000" + } + }, + "sync_info": { + "latest_block_hash": "8396B93E355AD80EED8167A04BB9858A315A8BEB482547DE16A6CD82BC11551B", + "latest_app_hash": "22419E041D6997EE75FF66F7F537A3D36122B220EAB89A9C246FEF680FB1C97A", + "latest_block_height": "86392", + "latest_block_time": "2022-02-24T14:32:08.673989Z", + "earliest_block_hash": "0A73CFE8566D4D4FBFE3178D9BCBAD483FD689854CA8012FF1457F8EC4598132", + "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", + "earliest_block_height": "1", + "earliest_block_time": "2022-01-20T09:04:21.549736Z", + "catching_up": false + }, + "validator_info": { + "address": "6FD56E6AA1EEDAD227AFAB6B9DE631719D4A3691", + "pub_key": { + "type": "tendermint/PubKeyEd25519", + "value": "mR5V/QWOv/mJYyNmlsl3mfxKy1PNaOzdztyas4NF2BA=" + }, + "voting_power": "10" + } + } +} +2022-02-24T14:32:14.052503Z DEBUG ThreadId(21) Incoming response: { + "jsonrpc": "2.0", + "id": "0ca35e64-ea98-4fbf-bd66-c3291128ace9", + "result": {} +} + +... +``` + +The two DEBUG log lines above were emitted by the `tendermint-rpc` crate. + diff --git a/guide/src/advanced/troubleshooting/patch-gaia.md b/guide/src/advanced/troubleshooting/patch-gaia.md new file mode 100644 index 0000000000..667a932437 --- /dev/null +++ b/guide/src/advanced/troubleshooting/patch-gaia.md @@ -0,0 +1,75 @@ +# Patch Gaia + +The guide below refers specifically to patching your gaia chain so that the +relayer can initiate the closing of channels by submitting a [`ChanCloseInit`][chan-close] message. +Without this modification, the transaction will be rejected. +We also describe how to test the channel closing feature. + +- Clone the Cosmos SDK + + ```shell + git clone https://github.com/cosmos/cosmos-sdk.git ~/go/src/github.com/cosmos/cosmos-sdk + cd ~/go/src/github.com/cosmos/cosmos-sdk + ``` + +- Apply these diffs: + + ``` + --- a/x/ibc/applications/transfer/module.go + +++ b/x/ibc/applications/transfer/module.go + @@ -305,7 +305,7 @@ func (am AppModule) OnChanCloseInit( + channelID string, + ) error { + // Disallow user-initiated channel closing for transfer channels + - return sdkerrors.Wrap(sdkerrors.ErrInvalidRequest, "user cannot close channel") + + return nil + } + ``` + +- Append the line below (watch for the placeholder ``) as the last line + in your `go.mod` in the gaia clone: + +```replace github.com/cosmos/cosmos-sdk => /Users//go/src/github.com/cosmos/cosmos-sdk``` + +- Now `make build` and `make install` your local copy of gaia + +In order to test the correct operation during the channel close, perform the steps below. + +- The channel should be in state open-open: + +- Transfer of 5555 samoleans from `ibc-1` to `ibc-0`. This results in a + Tx to `ibc-1` for a `MsgTransfer` packet. + Make sure you're not relaying this packet (the relayer should not be running on + this path). + + ```shell + hermes tx ft-transfer --receiver-chain ibc-0 --sender-chain ibc-1 --sender-port transfer --sender-channel channel-1 --amount 5555 --timeout-height-offset 1000 --number-msgs 1 --denom samoleans + ``` + +- Now do the first step of channel closing: the channel will transition +to close-open: + + ```shell + hermes --config config.toml tx chan-close-init --receiver-chain ibc-0 --sender-chain ibc-1 --receiver-connection connection-0 --receiver-port transfer --sender-port transfer --receiver-channel channel-0 --sender-channel channel-1 + ``` + +- Trigger timeout on close to ibc-1 + + ```shell + hermes --config config.toml tx packet-recv --receiver-chain ibc-0 --sender-chain ibc-1 --sender-port transfer --sender-channel channel-1 + ``` + +- Close the channel + + ```shell + hermes --config config.toml tx chan-close-confirm --receiver-chain ibc-1 --sender-chain ibc-0 --receiver-connection connection-1 --receiver-port transfer --sender-port transfer --receiver-channel channel-1 --sender-channel channel-0 + ``` + +- Verify that the two ends are in Close state: + + ```shell + hermes --config config.toml query channel end --chain ibc-0 --port transfer --channel channel-0 + hermes --config config.toml query channel end --chain ibc-1 --port transfer --channel channel-1 + ``` + +[chan-close]: ../../documentation/commands/tx/channel-close.md#channel-close-init diff --git a/guide/src/advanced/troubleshooting/profiling.md b/guide/src/advanced/troubleshooting/profiling.md new file mode 100644 index 0000000000..1a76dc71a0 --- /dev/null +++ b/guide/src/advanced/troubleshooting/profiling.md @@ -0,0 +1,125 @@ +# Profiling + +The `relayer` crate provides a `time!` macro which can be used to measure how much time is spent between the invocation of the macro and the end of the enclosing scope. + +### Setup + +The `time!` macro has no effect unless the `profiling` feature of the `relayer` crate is enabled. + +To enable it, one must compile the `relayer-cli` crate with the `--features=profiling` flag. + +a) One way is to build the `relayer` binary and update the `hermes` alias to point to the executable: + +```shell +cd relayer-cli/ +cargo build --features=profiling +``` + +b) Alternatively, one can use the `cargo run` command and update the alias accordingly: + +```shell +alias hermes='cargo run --features=profiling --manifest-path=relayer-cli/Cargo.toml --' +``` + +The `--manifest-path=relayer-cli/Cargo.toml` flag is needed for `cargo run` to accept the `--features` flag. + +### Example + +```rust +fn my_function(x: u32) -> u32 { + time!("myfunction: x={}", x); // A + + std::thread::sleep(Duration::from_secs(1)); + + { + time!("inner operation"); // B + + std::thread::sleep(Duration::from_secs(2)); + + // timer B ends here + } + + x + 1 + + // timer A ends here +} +``` + +#### Output + +``` +Jan 20 11:28:46.841 INFO relayer::macros::profiling: ⏳ myfunction: x=42 - start +Jan 20 11:28:47.842 INFO relayer::macros::profiling: ⏳ inner operation - start +Jan 20 11:28:49.846 INFO relayer::macros::profiling: ⏳ inner operation - elapsed: 2004ms +Jan 20 11:28:49.847 INFO relayer::macros::profiling: ⏳ myfunction: x=42 - elapsed: 3005ms +``` + +Profiling is useful for tracking down unusually slow methods. +Each transaction or query usually consists of multiple lower-level methods, +and it's often not clear which of these are the culprit for low performance. +With profiling enabled, `hermes` will output timing information for individual +methods involved in a command. + +__NOTE__: To be able to see the profiling output, the realyer needs to be compiled with +the `profiling` feature and the [log level][log-level] should be `info` level or lower. + +#### Example output for `tx conn-init` command + +``` +hermes --config config.toml tx conn-init --b-chain ibc-0 --a-chain ibc-1 --b-client 07-tendermint-0 --a-client 07-tendermint-0 +``` + +``` +Apr 13 20:58:21.225 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - start +Apr 13 20:58:21.230 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - elapsed: 4ms +Apr 13 20:58:21.230 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - start +Apr 13 20:58:21.235 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - elapsed: 5ms +Apr 13 20:58:21.235 INFO ibc_relayer::event::monitor: running listener chain.id=ibc-1 +Apr 13 20:58:21.236 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - start +Apr 13 20:58:21.239 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - elapsed: 2ms +Apr 13 20:58:21.239 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - start +Apr 13 20:58:21.244 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - elapsed: 4ms +Apr 13 20:58:21.244 INFO ibc_relayer::event::monitor: running listener chain.id=ibc-0 +Apr 13 20:58:21.244 INFO ibc_relayer::macros::profiling: ⏳ get_signer - start +Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ get_signer - elapsed: 1ms +Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ query_latest_height - start +Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ block_on - start +Apr 13 20:58:21.248 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 1ms +Apr 13 20:58:21.249 INFO ibc_relayer::macros::profiling: ⏳ query_latest_height - elapsed: 3ms +Apr 13 20:58:21.250 INFO ibc_relayer::macros::profiling: ⏳ unbonding_period - start +Apr 13 20:58:21.250 INFO ibc_relayer::macros::profiling: ⏳ block_on - start +Apr 13 20:58:21.251 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 0ms +Apr 13 20:58:21.270 INFO ibc_relayer::macros::profiling: ⏳ block_on - start +Apr 13 20:58:21.273 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 2ms +Apr 13 20:58:21.273 INFO ibc_relayer::macros::profiling: ⏳ unbonding_period - elapsed: 23ms +Apr 13 20:58:21.279 INFO ibc_relayer::macros::profiling: ⏳ build_consensus_state - start +Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ build_consensus_state - elapsed: 0ms +Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ send_msgs - start +Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ send_tx - start +Apr 13 20:58:21.282 INFO ibc_relayer::macros::profiling: ⏳ PK "03f17d2c094ee68cfcedb2c2f2b7dec6cd82ea158ac1c32d3de0ca8b288a3c8bfa" - start +Apr 13 20:58:21.282 INFO ibc_relayer::macros::profiling: ⏳ block_on - start +Apr 13 20:58:21.285 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 3ms +Apr 13 20:58:21.296 INFO ibc_relayer::macros::profiling: ⏳ block_on - start +Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 1367ms +Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ PK "03f17d2c094ee68cfcedb2c2f2b7dec6cd82ea158ac1c32d3de0ca8b288a3c8bfa" - elapsed: 1382ms +Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ send_tx - elapsed: 1384ms +Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ send_msgs - elapsed: 1384ms +Success: CreateClient( + CreateClient( + Attributes { + height: Height { + revision: 0, + height: 10675, + }, + client_id: ClientId( + "07-tendermint-7", + ), + client_type: Tendermint, + consensus_height: Height { + revision: 1, + height: 10663, + }, + }, + ), +) +``` diff --git a/guide/src/assets/docker-compose.yaml b/guide/src/assets/docker-compose.yaml new file mode 100644 index 0000000000..107c75c8e6 --- /dev/null +++ b/guide/src/assets/docker-compose.yaml @@ -0,0 +1,40 @@ +version: "3" + +networks: + loki: + driver: bridge + prometheus: + driver: bridge + +services: + loki: + image: grafana/loki:2.6.0 + ports: + - "3100:3100" + command: -config.file=/etc/loki/local-config.yaml + networks: + - loki + + promtail: + image: grafana/promtail:2.6.0 + volumes: + - /var/log:/var/log + command: -config.file=/etc/promtail/config.yml + networks: + - loki + + grafana: + image: grafana/grafana:8.2.6 + ports: + - "3000:3000" + networks: + - loki + - prometheus + + prometheus: + image: prom/prometheus:v2.38.0 + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml + command: --config.file=/etc/prometheus/prometheus.yml + networks: + - prometheus diff --git a/guide/src/assets/grafana_template.json b/guide/src/assets/grafana_template.json new file mode 100644 index 0000000000..06ed330629 --- /dev/null +++ b/guide/src/assets/grafana_template.json @@ -0,0 +1,2484 @@ +{ + "__inputs": [ + { + "name": "DS_PROMETHEUS", + "label": "Prometheus", + "description": "", + "type": "datasource", + "pluginId": "prometheus", + "pluginName": "Prometheus" + }, + { + "name": "DS_LOKI", + "label": "Loki", + "description": "", + "type": "datasource", + "pluginId": "loki", + "pluginName": "Loki" + } + ], + "__elements": {}, + "__requires": [ + { + "type": "panel", + "id": "barchart", + "name": "Bar chart", + "version": "" + }, + { + "type": "grafana", + "id": "grafana", + "name": "Grafana", + "version": "9.0.7" + }, + { + "type": "panel", + "id": "logs", + "name": "Logs", + "version": "" + }, + { + "type": "datasource", + "id": "loki", + "name": "Loki", + "version": "1.0.0" + }, + { + "type": "datasource", + "id": "prometheus", + "name": "Prometheus", + "version": "1.0.0" + }, + { + "type": "panel", + "id": "table", + "name": "Table", + "version": "" + }, + { + "type": "panel", + "id": "text", + "name": "Text", + "version": "" + }, + { + "type": "panel", + "id": "timeseries", + "name": "Time series", + "version": "" + } + ], + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "target": { + "limit": 100, + "matchAny": false, + "tags": [], + "type": "dashboard" + }, + "type": "dashboard" + }, + { + "datasource": { + "type": "loki", + "uid": "${DS_LOKI}" + }, + "enable": true, + "expr": "{filename=\"/var/log/hermes.log\"} |= \"ERROR\"", + "iconColor": "red", + "name": "Errors", + "target": {} + } + ] + }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 0, + "id": null, + "links": [], + "liveNow": false, + "panels": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "gridPos": { + "h": 3, + "w": 24, + "x": 0, + "y": 0 + }, + "id": 62, + "options": { + "content": "# Hermes Grafana Dashboard\n\nhttp://hermes.informal.systems/documentation/telemetry/operators.html to learn more about the metrics.", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "type": "text" + }, + { + "datasource": { + "type": "loki", + "uid": "${DS_LOKI}" + }, + "gridPos": { + "h": 12, + "w": 24, + "x": 0, + "y": 3 + }, + "id": 60, + "options": { + "dedupStrategy": "none", + "enableLogDetails": true, + "prettifyLogMessage": false, + "showCommonLabels": false, + "showLabels": false, + "showTime": false, + "sortOrder": "Descending", + "wrapLogMessage": false + }, + "targets": [ + { + "datasource": { + "type": "loki", + "uid": "${DS_LOKI}" + }, + "editorMode": "builder", + "expr": "{filename=\"/var/log/hermes.log\"}", + "queryType": "range", + "refId": "A" + } + ], + "title": "Hermes logs", + "type": "logs" + }, + { + "gridPos": { + "h": 2, + "w": 24, + "x": 0, + "y": 15 + }, + "id": 50, + "options": { + "content": "# Is hermes active ?", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "type": "text" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates if you have enough funds on your wallet. Hermes can not relay without spending gas. Thus, it is important to set alarms which monitor the gas.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "fillOpacity": 80, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineWidth": 1, + "scaleDistribution": { + "type": "linear" + } + }, + "decimals": 0, + "mappings": [], + "min": -1, + "thresholds": { + "mode": "percentage", + "steps": [ + { + "color": "green", + "value": null + } + ] + }, + "unit": "short" + }, + "overrides": [ + { + "matcher": { + "id": "byType", + "options": "time" + }, + "properties": [ + { + "id": "custom.axisPlacement", + "value": "hidden" + } + ] + } + ] + }, + "gridPos": { + "h": 7, + "w": 8, + "x": 0, + "y": 17 + }, + "id": 1, + "options": { + "barRadius": 0, + "barWidth": 0.97, + "groupWidth": 0.7, + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "orientation": "horizontal", + "showValue": "auto", + "stacking": "none", + "tooltip": { + "mode": "single", + "sort": "none" + }, + "xTickLabelRotation": 0, + "xTickLabelSpacing": 100 + }, + "pluginVersion": "9.0.6", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "code", + "exemplar": false, + "expr": "wallet_balance{job=\"hermes\"}", + "hide": false, + "instant": true, + "legendFormat": "{{chain}}: {{account}} ({{instance}})", + "range": false, + "refId": "A" + } + ], + "title": "Wallet balances", + "transformations": [], + "transparent": true, + "type": "barchart" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates if clients are getting updated.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 7, + "w": 8, + "x": 8, + "y": 17 + }, + "id": 52, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(client_updates_submitted{job=\"hermes\"}[1m])", + "legendFormat": "{{src_chain}} -> {{dst_chain}}:{{client}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "client_updates_submitted over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates if Hermes is submitting messages to a specific chain ", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 7, + "w": 8, + "x": 16, + "y": 17 + }, + "id": 40, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(total_messages_submitted{job=\"hermes\"}[1m])", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "total_messages_submitted over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates if you are spending gas and how much you are spending.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 0, + "y": 24 + }, + "id": 3, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(wallet_balance{job=\"hermes\"}[1m])", + "legendFormat": "{{chain}}: {{account}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "Gas variation over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "This panel indicates which type of workers are active for every instance.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 8, + "y": 24 + }, + "id": 42, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "exemplar": false, + "expr": "workers{job=\"hermes\"}", + "instant": false, + "legendFormat": "{{instance}}:{{type}}", + "range": true, + "refId": "A" + } + ], + "title": "Current number of workers", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the latency rate for all transactions confirmed by each chain.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ms" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 16, + "y": 24 + }, + "id": 35, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "histogram_quantile(0.95, sum by(le, chain) (rate(tx_latency_confirmed_bucket[5m])))", + "legendFormat": "{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "95th quantile of tx_latency_confirmed rate over 5 minutes", + "type": "timeseries" + }, + { + "description": "", + "gridPos": { + "h": 2, + "w": 24, + "x": 0, + "y": 32 + }, + "id": 25, + "options": { + "content": "# Are transaction successful ?\n", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "type": "text" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Represents the sequence number and the date of the oldest pending packet. Use this metric to identify stuck packets.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "thresholds" + }, + "custom": { + "align": "auto", + "displayMode": "auto", + "inspect": false + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [ + { + "matcher": { + "id": "byName", + "options": "ibc-0:channel-0/transfer-ibc-1 (localhost:3001)" + }, + "properties": [ + { + "id": "custom.width", + "value": 483 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "Time" + }, + "properties": [ + { + "id": "custom.width", + "value": 102 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "__name__" + }, + "properties": [ + { + "id": "custom.width", + "value": 162 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "chain" + }, + "properties": [ + { + "id": "custom.width", + "value": 386 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "channel" + }, + "properties": [ + { + "id": "custom.width", + "value": 263 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "counterparty" + }, + "properties": [ + { + "id": "custom.width", + "value": 330 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "instance" + }, + "properties": [ + { + "id": "custom.width", + "value": 330 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "port" + }, + "properties": [ + { + "id": "custom.width", + "value": 142 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "job" + }, + "properties": [ + { + "id": "custom.width", + "value": 75 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "Value #A" + }, + "properties": [ + { + "id": "custom.width", + "value": 75 + } + ] + }, + { + "matcher": { + "id": "byName", + "options": "Sequence" + }, + "properties": [ + { + "id": "custom.width" + } + ] + } + ] + }, + "gridPos": { + "h": 9, + "w": 24, + "x": 0, + "y": 34 + }, + "id": 9, + "options": { + "footer": { + "fields": "", + "reducer": [ + "sum" + ], + "show": false + }, + "frameIndex": 0, + "showHeader": true, + "sortBy": [] + }, + "pluginVersion": "9.0.7", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "exemplar": false, + "expr": "backlog_oldest_sequence{job=\"hermes\"}", + "format": "table", + "instant": true, + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": false, + "refId": "A" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "exemplar": false, + "expr": "backlog_oldest_timestamp{job=\"hermes\"}", + "format": "table", + "hide": false, + "instant": true, + "legendFormat": "__auto", + "range": false, + "refId": "B" + } + ], + "title": "Oldest pending packets", + "transformations": [ + { + "id": "groupBy", + "options": { + "fields": { + "Value #A": { + "aggregations": [ + "last" + ], + "operation": "aggregate" + }, + "Value #B": { + "aggregations": [ + "last" + ], + "operation": "aggregate" + }, + "chain": { + "aggregations": [], + "operation": "groupby" + }, + "channel": { + "aggregations": [], + "operation": "groupby" + }, + "counterparty": { + "aggregations": [], + "operation": "groupby" + }, + "instance": { + "aggregations": [], + "operation": "groupby" + }, + "job": { + "aggregations": [], + "operation": "groupby" + }, + "port": { + "aggregations": [], + "operation": "groupby" + } + } + } + }, + { + "id": "convertFieldType", + "options": { + "conversions": [ + { + "destinationType": "time", + "targetField": "Value #B (last)" + } + ], + "fields": {} + } + }, + { + "id": "concatenate", + "options": {} + }, + { + "id": "organize", + "options": { + "excludeByName": { + "chain 2": true, + "channel 2": true, + "counterparty 2": true, + "instance 2": true, + "job 1": true, + "job 2": true, + "port 2": true + }, + "indexByName": {}, + "renameByName": { + "Value #A (last)": "Sequence", + "Value #B (last)": "Date", + "instance 1": "", + "port 2": "" + } + } + } + ], + "type": "table" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates how many packets are being processed by Hermes. If this value stays constantly more than 0, it could mean that a packet is stuck.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 43 + }, + "id": 5, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "pluginVersion": "9.0.6", + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "exemplar": false, + "expr": "backlog_size{job=\"hermes\"}", + "instant": false, + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "Pending packet per path", + "transformations": [], + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates how many `receive_packets` were processed by the relayer. It can be used with `send_packet_events` as every `send_packet_event` should trigger the processing of a `receive_packet`.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 43 + }, + "id": 23, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(receive_packets_confirmed{job=\"hermes\"}[1m])", + "legendFormat": "{{src_chain}}:{{src_channel}}/{{src_port}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "receive_packets_confirmed over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates how many `timeout_packets` were processed by the relayer. It can be used with `timeout_packet_events` as every `timeout_event` should be processed by the relayer.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 52 + }, + "id": 21, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(timeout_packets_confirmed{job=\"hermes\"}[1m])", + "legendFormat": "{{src_chain}}:{{src_channel}}/{{src_port}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "timeout_packets_confirmed over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates how many acknowledgements were processed by the relayer. It can be used with `acknowledgment_events` as every event should be processed by the relayer.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 52 + }, + "id": 17, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(acknowledgment_packets_confirmed{job=\"hermes\"}[1m])", + "legendFormat": "{{src_chain}}:{{src_channel}}/{{src_port}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "acknowledgment_packets_confirmed over 1 minute", + "type": "timeseries" + }, + { + "description": "", + "gridPos": { + "h": 2, + "w": 24, + "x": 0, + "y": 61 + }, + "id": 31, + "options": { + "content": "# What is the overall IBC status of each network?\r\n\r\n", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "targets": [ + { + "expr": "", + "range": true, + "refId": "A" + } + ], + "type": "text" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the number of `send_packet_event` observed.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 0, + "y": 63 + }, + "id": 11, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(send_packet_events{job=\"hermes\"}[1m])", + "interval": "", + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "send_packets_events over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the number of `acknowledgement_event` observed.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 8, + "y": 63 + }, + "id": 15, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(acknowledgement_events{job=\"hermes\"}[1m])", + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "acknowledgement_events over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the number of `timeout_event` observed.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 16, + "y": 63 + }, + "id": 19, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(timeout_events{job=\"hermes\"}[1m])", + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "timeout_events over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the number of `event` observed via the websocket subcription.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 0, + "y": 71 + }, + "id": 44, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(ws_events{job=\"hermes\"}[1m])", + "interval": "", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "ws_events received over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the number of times Hermes reconnected to the websocket.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 8, + "y": 71 + }, + "id": 46, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(ws_reconnect{job=\"hermes\"}[1m])", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "ws_reconnect over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicate the number of queries per instance and chain.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 8, + "x": 16, + "y": 71 + }, + "id": 48, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "code", + "expr": "sum(delta(queries{job=\"hermes\"}[1m])) by(instance,chain)", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "RPC queries sent over 1 minute", + "transformations": [], + "type": "timeseries" + }, + { + "gridPos": { + "h": 2, + "w": 24, + "x": 0, + "y": 79 + }, + "id": 36, + "options": { + "content": "# How efficient and how secure is the IBC status on each network ?\n\n", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "type": "text" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Cleared `acknowledgment_events` rate per path. It is an indication that IBC packet relaying may be unsuccessful and that Hermes periodically finds packets to clear (i.e., unblock).", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 0, + "y": 81 + }, + "id": 33, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(cleared_acknowledgment_events{job=\"hermes\"}[1m])", + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "cleared_acknowledgment_events over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Cleared `send_packet_events` rate per path. It is an indication that IBC packet relaying may be unsuccessful and that Hermes periodically finds packets to clear (i.e., unblock).", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 9, + "w": 12, + "x": 12, + "y": 81 + }, + "id": 13, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(cleared_send_packet_events{job=\"hermes\"}[1m])", + "legendFormat": "{{chain}}:{{channel}}/{{port}}-{{counterparty}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "cleared_send_packet_events over 1 minute", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "Indicates the latency rate for all transactions submitted to each chain.", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + }, + "unit": "ms" + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 90 + }, + "id": 37, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "histogram_quantile(0.95, sum by(le, chain, instance) (rate(tx_latency_submitted_bucket[5m])))", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "95th quantile of tx_latency_submitted rate over 5 minutes", + "type": "timeseries" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 90 + }, + "id": 54, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "sum by(chain, instance) (delta(queries_cache_hits{job=\"hermes\"}[1m]))", + "legendFormat": "{{instance}}:{{chain}}", + "range": true, + "refId": "A" + } + ], + "title": "queries_cache_hits over 1 minute", + "type": "timeseries" + }, + { + "gridPos": { + "h": 2, + "w": 24, + "x": 0, + "y": 98 + }, + "id": 58, + "options": { + "content": "# Extra", + "mode": "markdown" + }, + "pluginVersion": "9.0.7", + "type": "text" + }, + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "description": "If `misbehaviour = true` then hermes will detect misbehaviours from clients and stop relaying to this client if one is detected. It is possible to set an alarm on this. ", + "fieldConfig": { + "defaults": { + "color": { + "mode": "palette-classic" + }, + "custom": { + "axisLabel": "", + "axisPlacement": "auto", + "barAlignment": 0, + "drawStyle": "line", + "fillOpacity": 0, + "gradientMode": "none", + "hideFrom": { + "legend": false, + "tooltip": false, + "viz": false + }, + "lineInterpolation": "linear", + "lineWidth": 1, + "pointSize": 5, + "scaleDistribution": { + "type": "linear" + }, + "showPoints": "auto", + "spanNulls": false, + "stacking": { + "group": "A", + "mode": "none" + }, + "thresholdsStyle": { + "mode": "off" + } + }, + "mappings": [], + "thresholds": { + "mode": "absolute", + "steps": [ + { + "color": "green", + "value": null + }, + { + "color": "red", + "value": 80 + } + ] + } + }, + "overrides": [] + }, + "gridPos": { + "h": 10, + "w": 24, + "x": 0, + "y": 100 + }, + "id": 56, + "options": { + "legend": { + "calcs": [], + "displayMode": "list", + "placement": "bottom" + }, + "tooltip": { + "mode": "single", + "sort": "none" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "${DS_PROMETHEUS}" + }, + "editorMode": "builder", + "expr": "delta(client_misbehaviours_submitted[5m])", + "legendFormat": "{{src_chain}}-{{dst_chain}}:{{client}} ({{instance}})", + "range": true, + "refId": "A" + } + ], + "title": "client_misbehaviours_submitted over 5 minutes", + "type": "timeseries" + } + ], + "refresh": "5s", + "schemaVersion": 36, + "style": "dark", + "tags": [], + "templating": { + "list": [] + }, + "time": { + "from": "now-30m", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "Grafana template", + "uid": "lrkGhUmVz", + "version": 1, + "weekStart": "" +} \ No newline at end of file diff --git a/guide/src/assets/prometheus.yml b/guide/src/assets/prometheus.yml new file mode 100644 index 0000000000..42aea9727b --- /dev/null +++ b/guide/src/assets/prometheus.yml @@ -0,0 +1,29 @@ +# my global config +global: + scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute. + evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. + # scrape_timeout is set to the global default (10s). + +# Alertmanager configuration +alerting: + alertmanagers: + - static_configs: + - targets: + # - alertmanager:9093 + +# Load rules once and periodically evaluate them according to the global 'evaluation_interval'. +rule_files: + # - "first_rules.yml" + # - "second_rules.yml" + +# A scrape configuration containing exactly one endpoint to scrape: +# Here it's Prometheus itself. +scrape_configs: + # The job name is added as a label `job=` to any timeseries scraped from this config. + - job_name: "hermes" + + # metrics_path defaults to '/metrics' + # scheme defaults to 'http'. + + static_configs: + - targets: ["host.docker.internal:3001"] diff --git a/guide/src/commands/index.md b/guide/src/commands/index.md deleted file mode 100644 index 931dad6e5c..0000000000 --- a/guide/src/commands/index.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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. - -**[Config](./config.md)** - -Commands to manage configuration file, in particular to validate it. - -**[Path Setup](./path-setup/index.md)** - -Commands to manage clients, connections, channels. - -**[Relaying](./relaying/index.md)** - -Commands to start the relayer and relay packets. - -**[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 - -**[Transactions](./tx/index.md)** - -Commands to submit individual transactions to configured chains diff --git a/guide/src/commands/config.md b/guide/src/documentation/commands/config.md similarity index 100% rename from guide/src/commands/config.md rename to guide/src/documentation/commands/config.md diff --git a/guide/src/commands/global.md b/guide/src/documentation/commands/global.md similarity index 92% rename from guide/src/commands/global.md rename to guide/src/documentation/commands/global.md index c2dbeb7dbf..a6de65269d 100644 --- a/guide/src/commands/global.md +++ b/guide/src/documentation/commands/global.md @@ -3,7 +3,7 @@ Hermes accepts _global_ options which affect all commands. ```shell -hermes v1.0.0 +hermes {{#template ../../templates/version}} Informal Systems Implementation of `hermes`, an IBC Relayer developed in Rust. @@ -14,8 +14,8 @@ FLAGS: ## Ordering of command-line options -The global options must be specified right after the `hermes` command and _before_ any subcommand. -The non-global options have to be specified _after_ the subcommand. +The global options must be specified right after the `hermes` command and _before_ any sub-command. +The non-global options have to be specified _after_ the sub-command. ```shell hermes subcommand @@ -61,7 +61,7 @@ The first three lines are printed to `stderr`, while the last line with a `"resu __Example__ -To improve the readability, pipe all of the output to `jq`: +To improve the readability, pipe all the output to `jq`: ``` hermes --config /home/my_chain.toml --json create client --host-chain ibc-0 --reference-chain ibc-1 2>&1 | jq @@ -115,12 +115,14 @@ hermes --config /home/my_chain.toml --json create client --host-chain ibc-0 --re __Example__ -To extract the identifer of the newly created client above: +To extract the identifier of the newly created client above: ``` hermes --config /home/my_chain.toml --json create client --host-chain ibc-0 --reference-chain ibc-1 | jq '.result.CreateClient.client_id' ``` +Which should output: + ``` "07-tendermint-2" ``` diff --git a/guide/src/documentation/commands/index.md b/guide/src/documentation/commands/index.md new file mode 100644 index 0000000000..5737a123e3 --- /dev/null +++ b/guide/src/documentation/commands/index.md @@ -0,0 +1,41 @@ +# 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. + +* **[Config](./config.md)** + + * Commands to manage configuration file, in particular to validate it. + +* **[Path Setup](./path-setup/index.md)** + + * Commands to manage clients, connections, channels. + +* **[Relaying](./relaying/index.md)** + + * Commands to start the relayer and relay packets. + +* **[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 + +* **[Transactions](./tx/index.md)** + + * Commands to submit individual transactions to configured chains diff --git a/guide/src/commands/keys/index.md b/guide/src/documentation/commands/keys/index.md similarity index 100% rename from guide/src/commands/keys/index.md rename to guide/src/documentation/commands/keys/index.md diff --git a/guide/src/commands/listen/index.md b/guide/src/documentation/commands/listen/index.md similarity index 97% rename from guide/src/commands/listen/index.md rename to guide/src/documentation/commands/listen/index.md index 6a9ebddc09..f9cb3e396b 100644 --- a/guide/src/commands/listen/index.md +++ b/guide/src/documentation/commands/listen/index.md @@ -148,7 +148,7 @@ EventBatch { ## Filter events -The `listen` command accepts an `--event` flag to specify which event types to listen for. +The `listen` command accepts a `--event` flag to specify which event types to listen for. At the moment, two event types are available: - `NewBlock` diff --git a/guide/src/commands/misbehaviour/index.md b/guide/src/documentation/commands/misbehaviour/index.md similarity index 100% rename from guide/src/commands/misbehaviour/index.md rename to guide/src/documentation/commands/misbehaviour/index.md diff --git a/guide/src/commands/path-setup/channels.md b/guide/src/documentation/commands/path-setup/channels.md similarity index 100% rename from guide/src/commands/path-setup/channels.md rename to guide/src/documentation/commands/path-setup/channels.md diff --git a/guide/src/commands/path-setup/clients.md b/guide/src/documentation/commands/path-setup/clients.md similarity index 100% rename from guide/src/commands/path-setup/clients.md rename to guide/src/documentation/commands/path-setup/clients.md diff --git a/guide/src/commands/path-setup/connections.md b/guide/src/documentation/commands/path-setup/connections.md similarity index 100% rename from guide/src/commands/path-setup/connections.md rename to guide/src/documentation/commands/path-setup/connections.md diff --git a/guide/src/commands/path-setup/index.md b/guide/src/documentation/commands/path-setup/index.md similarity index 100% rename from guide/src/commands/path-setup/index.md rename to guide/src/documentation/commands/path-setup/index.md diff --git a/guide/src/commands/queries/channel.md b/guide/src/documentation/commands/queries/channel.md similarity index 98% rename from guide/src/commands/queries/channel.md rename to guide/src/documentation/commands/queries/channel.md index 1824ebef73..b013820b1c 100644 --- a/guide/src/commands/queries/channel.md +++ b/guide/src/documentation/commands/queries/channel.md @@ -17,6 +17,12 @@ OPTIONS: --counterparty-chain Filter the query response by the this counterparty chain + -h, --help + Print help information + + --show-counterparty + Show the counterparty chain, port, and channel + --verbose Enable verbose output, displaying the client and connection ids for each channel in the response diff --git a/guide/src/commands/queries/client.md b/guide/src/documentation/commands/queries/client.md similarity index 100% rename from guide/src/commands/queries/client.md rename to guide/src/documentation/commands/queries/client.md diff --git a/guide/src/commands/queries/connection.md b/guide/src/documentation/commands/queries/connection.md similarity index 100% rename from guide/src/commands/queries/connection.md rename to guide/src/documentation/commands/queries/connection.md diff --git a/guide/src/commands/queries/index.md b/guide/src/documentation/commands/queries/index.md similarity index 100% rename from guide/src/commands/queries/index.md rename to guide/src/documentation/commands/queries/index.md diff --git a/guide/src/commands/queries/packet.md b/guide/src/documentation/commands/queries/packet.md similarity index 100% rename from guide/src/commands/queries/packet.md rename to guide/src/documentation/commands/queries/packet.md diff --git a/guide/src/commands/queries/transfer.md b/guide/src/documentation/commands/queries/transfer.md similarity index 100% rename from guide/src/commands/queries/transfer.md rename to guide/src/documentation/commands/queries/transfer.md diff --git a/guide/src/commands/queries/tx.md b/guide/src/documentation/commands/queries/tx.md similarity index 100% rename from guide/src/commands/queries/tx.md rename to guide/src/documentation/commands/queries/tx.md diff --git a/guide/src/commands/relaying/clear.md b/guide/src/documentation/commands/relaying/clear.md similarity index 100% rename from guide/src/commands/relaying/clear.md rename to guide/src/documentation/commands/relaying/clear.md diff --git a/guide/src/commands/relaying/handshakes.md b/guide/src/documentation/commands/relaying/handshakes.md similarity index 100% rename from guide/src/commands/relaying/handshakes.md rename to guide/src/documentation/commands/relaying/handshakes.md diff --git a/guide/src/commands/relaying/index.md b/guide/src/documentation/commands/relaying/index.md similarity index 79% rename from guide/src/commands/relaying/index.md rename to guide/src/documentation/commands/relaying/index.md index 0179dd38b3..987638da3c 100644 --- a/guide/src/commands/relaying/index.md +++ b/guide/src/documentation/commands/relaying/index.md @@ -22,4 +22,4 @@ OPTIONS: --full-scan Force a full scan of the chains for clients, connections and channels ``` -As described in next sub-sections, the type of relaying can be configured in the `global` section of the configuration file, by specifying different values in `strategy` field. +As described in next subsections, the type of relaying can be configured in the `global` section of the configuration file, by specifying different values in `strategy` field. diff --git a/guide/src/commands/relaying/packets.md b/guide/src/documentation/commands/relaying/packets.md similarity index 100% rename from guide/src/commands/relaying/packets.md rename to guide/src/documentation/commands/relaying/packets.md diff --git a/guide/src/commands/tx/channel-close.md b/guide/src/documentation/commands/tx/channel-close.md similarity index 97% rename from guide/src/commands/tx/channel-close.md rename to guide/src/documentation/commands/tx/channel-close.md index 99874ddb23..af289607c5 100644 --- a/guide/src/commands/tx/channel-close.md +++ b/guide/src/documentation/commands/tx/channel-close.md @@ -154,4 +154,4 @@ Success: CloseConfirmChannel( __NOTE__: The `cosmos-sdk` transfer module implementation does not allow the user (`hermes` in this case) to initiate the closing of channels. Therefore, when using the Gaia release image, the `chan-close-init` command fails as the `MsgChannelCloseInit` message included in the transaction is rejected. -To be able to test channel closure, you need to [patch](../../help.md#patching-gaia) your gaia deployments. +To be able to test channel closure, you need to [patch](../../../advanced/troubleshooting/patch-gaia.md) your gaia deployments. diff --git a/guide/src/commands/tx/channel-open.md b/guide/src/documentation/commands/tx/channel-open.md similarity index 100% rename from guide/src/commands/tx/channel-open.md rename to guide/src/documentation/commands/tx/channel-open.md diff --git a/guide/src/commands/tx/connection.md b/guide/src/documentation/commands/tx/connection.md similarity index 100% rename from guide/src/commands/tx/connection.md rename to guide/src/documentation/commands/tx/connection.md diff --git a/guide/src/commands/tx/index.md b/guide/src/documentation/commands/tx/index.md similarity index 100% rename from guide/src/commands/tx/index.md rename to guide/src/documentation/commands/tx/index.md diff --git a/guide/src/commands/tx/packet.md b/guide/src/documentation/commands/tx/packet.md similarity index 99% rename from guide/src/commands/tx/packet.md rename to guide/src/documentation/commands/tx/packet.md index 825f36e3b3..30c1d3af44 100644 --- a/guide/src/commands/tx/packet.md +++ b/guide/src/documentation/commands/tx/packet.md @@ -108,7 +108,7 @@ Success: [ ## Relay receive and timeout packets -Use the `tx packet-recv` command to relay the packets sent but not yet received. If the sent packets have timed out then a timeout packet is sent to the source chain. +Use the `tx packet-recv` command to relay the packets sent but not yet received. If the packets sent have timed out then a timeout packet is sent to the source chain. ```shell USAGE: @@ -135,7 +135,7 @@ __Example__ Send the two transfer packets to the `ibc-1` module bound to the `transfer` port and the `channel-0`'s counterparty. -__NOTE__: The relayer prepends a client update message before the receive messages. +__NOTE__: The relayer prepends a client update message before the Receive messages. ```shell hermes tx packet-recv --reference-chain ibc-1 --host-chain ibc-0 --host-port transfer --host-channel channel-0 diff --git a/guide/src/commands/tx/upgrade.md b/guide/src/documentation/commands/tx/upgrade.md similarity index 90% rename from guide/src/commands/tx/upgrade.md rename to guide/src/documentation/commands/tx/upgrade.md index d566a3c330..30280ccaa6 100644 --- a/guide/src/commands/tx/upgrade.md +++ b/guide/src/documentation/commands/tx/upgrade.md @@ -47,7 +47,7 @@ REQUIRED: __Example__ -An upgrade proposal is made for `ibc-0`, for height `300` blocks from latest height, with `10000000stake` deposited. The proposal will include the upgraded client state constructed from the state of `07-tendermint-0` client on `ibc-1`. +An upgrade proposal is made for `ibc-0`, for height `300` blocks from the latest height, with `10000000stake` deposited. The proposal will include the upgraded client state constructed from the state of `07-tendermint-0` client on `ibc-1`. ```shell hermes tx upgrade-chain --reference-chain ibc-0 --host-chain ibc-1 --host-client 07-tendermint-0 --amount 10000000 --height-offset 300 diff --git a/guide/src/commands/upgrade/index.md b/guide/src/documentation/commands/upgrade/index.md similarity index 100% rename from guide/src/commands/upgrade/index.md rename to guide/src/documentation/commands/upgrade/index.md diff --git a/guide/src/commands/upgrade/test.md b/guide/src/documentation/commands/upgrade/test.md similarity index 92% rename from guide/src/commands/upgrade/test.md rename to guide/src/documentation/commands/upgrade/test.md index 0e1eb23d66..9317d2f6d5 100644 --- a/guide/src/commands/upgrade/test.md +++ b/guide/src/documentation/commands/upgrade/test.md @@ -2,7 +2,7 @@ ## Prerequisites -- gaiad `(v7.0.*)`, for example: +- Gaiad `(v7.0.*)`, for example: ```shell gaiad version --log_level error --long | head -n4 @@ -38,9 +38,9 @@ gaiad version --log_level error --long | head -n4 [ibc-1] ports_start_at = 27010 ``` -* Run the command `gm start` +* Run the command `{{#template ../../../templates/commands/gm/start}}` * Go to the file `$HOME/.gm/ibc-0/config/genesis.json` and change `max_deposit_period` and `voting_period` to a lower value, such as 120s -* Run the commands: `gm reset`, `gm hermes config` and `gm hermes keys` +* Run the commands: `{{#template ../../../templates/commands/gm/reset}}`, `{{#template ../../../templates/commands/gm/hermes_config}}` and `{{#template ../../../templates/commands/gm/hermes_keys}}` ### Test upgrading chain and client @@ -67,7 +67,7 @@ gaiad version --log_level error --long | head -n4 2. Create and submit an upgrade plan for chain `ibc-0`: - Use the hermes test command to make an upgrade proposal. In the example below a software upgrade proposal is made for `ibc-0`, for the height `300` blocks from latest height. `10000000stake` is deposited. + Use test command to make an upgrade proposal. In the example below a software upgrade proposal is made for `ibc-0`, for the height `300` blocks from the latest height. `10000000stake` is deposited. The proposal includes the upgraded client state constructed from the state of `07-tendermint-0` client on `ibc-1` that was created in the previous step. ```shell diff --git a/guide/src/config.md b/guide/src/documentation/configuration/configure-hermes.md similarity index 69% rename from guide/src/config.md rename to guide/src/documentation/configuration/configure-hermes.md index 5ea975a40f..9b0fc8201d 100644 --- a/guide/src/config.md +++ b/guide/src/documentation/configuration/configure-hermes.md @@ -1,4 +1,4 @@ -# Configuration +# Configure Hermes In order to run Hermes, you will need to have a configuration file. @@ -7,7 +7,7 @@ The format supported for the configuration file is [TOML](https://toml.io/en/). By default, Hermes expects the configuration file to be located at `$HOME/.hermes/config.toml`. This can be overridden by supplying the `--config` flag when invoking `hermes`, before the -name of the command to run, eg. `hermes --config my_config.toml query connection channels --chain ibc-1 --connection connection-1`. +name of the command to run, e.g. `hermes --config my_config.toml query connection channels --chain ibc-1 --connection connection-1`. > The current version of Hermes does not support managing the configuration file programmatically. > You will need to use a text editor to create the file and add content to it. @@ -25,7 +25,7 @@ hermes [--config CONFIG_FILE] COMMAND The configuration file must have one `global` section, and one `chains` section for each chain. > **Note:** As of 0.6.0, the Hermes configuration file is self-documented. -> Please read the configuration file [`config.toml`](https://github.com/informalsystems/ibc-rs/blob/v1.0.0/config.toml) +> Please read the configuration file [`config.toml`](https://github.com/informalsystems/ibc-rs/blob/{{#template ../../templates/version}}/config.toml) > itself for the most up-to-date documentation of parameters. By default, Hermes will relay on all channels available between all the configured chains. @@ -34,14 +34,14 @@ and as a destination (to relay packets that others chains have sent). For example, if there are only two chains configured, then Hermes will only relay packets between those two, i.e. the two chains will serve as a source for each other, and likewise as a destination for each other's relevant events. -Hermes will ignore all events that pertain to chains which are unknown (ie. not present in config.toml). +Hermes will ignore all events that pertain to chains which are unknown (i.e. not present in config.toml). -To restrict relaying on specific channels, or uni-directionally, you can use [packet filtering policies](https://github.com/informalsystems/ibc-rs/blob/v1.0.0/config.toml#L209-L231). +To restrict relaying on specific channels, or uni-directionally, you can use [packet filtering policies](https://github.com/informalsystems/ibc-rs/blob/{{#template ../../templates/version}}/config.toml#L209-L231). ## Adding private keys -For each chain configured you need to add a private key for that chain in order to submit [transactions](./commands/tx/index.md), -please refer to the [Keys](./commands/keys/index.md) sections in order to learn how to add the private keys that are used by the relayer. +For each chain configured you need to add a private key for that chain in order to submit [transactions](../commands/tx/index.md), +please refer to the [Keys](../commands/keys/index.md) sections in order to learn how to add the private keys that are used by the relayer. ## Connecting via TLS @@ -97,9 +97,30 @@ list = [ ] ``` -## Next steps +## Connecting to a full node protected by HTTP Basic Authentication -Now that you learned how to build the relayer and how to create a configuration file, you can go to the [`Two Chains`](./tutorials/local-chains/index.md) tutorial to learn how to perform some local testing connecting the relayer to two local chains. +To connect to a full node protected by [HTTP Basic Authentication][http-basic-auth], +specify the username and password in the `rpc_addr`, `grpc_addr` and `websocket_addr` settings +under the chain configuration in `config.toml`. -[log-level]: ./help.md#parametrizing-the-log-output-level +Here is an example with username `hello` and password `world`, assuming the RPC, WebSocket and gRPC servers +listen on domain `mydomain.com` with TLS enabled (HTTPS/WSS). + +```toml +[[chains]] +id = 'my-chain-0' + +# ... + +rpc_addr = 'https://hello:world@mydomain.com:26657' +grpc_addr = 'https://hello:world@mydomain.com:9090' +websocket_addr = 'wss://hello:world@mydomain.com:26657/websocket' + +# ... +``` + +> **Caution:** Warning: The "Basic" authentication scheme sends the credentials encoded but not encrypted. +> This would be completely insecure unless the exchange was over a secure connection (HTTPS/TLS). + +[http-basic-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication [ica]: https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md diff --git a/guide/src/documentation/configuration/description.md b/guide/src/documentation/configuration/description.md new file mode 100644 index 0000000000..67a9cc9a90 --- /dev/null +++ b/guide/src/documentation/configuration/description.md @@ -0,0 +1,9 @@ +# Description of the parameters + +This page provides a full example of a configuration file with two chains configured: + +>__NOTE__: Visit the [Relaying](../commands/relaying/index.md) section to learn more about Hermes' modes. + +```toml +{{#include ../../../../config.toml}} +``` diff --git a/guide/src/documentation/configuration/index.md b/guide/src/documentation/configuration/index.md new file mode 100644 index 0000000000..fa41b2fca3 --- /dev/null +++ b/guide/src/documentation/configuration/index.md @@ -0,0 +1,13 @@ +# Configuration + +This section includes everything you need to know to configure Hermes. + +--- + +## Sections + +* **[Configure Hermes](./configure-hermes.md)** + * Learn how to configure Hermes and some supported features. + +* **[Description of the parameters](./description.md)** + * Detailed description of every parameter of Hermes \ No newline at end of file diff --git a/guide/src/example-config.md b/guide/src/documentation/example-config.md similarity index 77% rename from guide/src/example-config.md rename to guide/src/documentation/example-config.md index a6a1095f3a..f6197b5d3d 100644 --- a/guide/src/example-config.md +++ b/guide/src/documentation/example-config.md @@ -3,5 +3,5 @@ Here is a full example of a configuration file with two chains configured: ```toml -{{#include ../../config.toml}} +{{#include ../../../config.toml}} ``` diff --git a/guide/src/documentation/index.md b/guide/src/documentation/index.md new file mode 100644 index 0000000000..e89e0a3e82 --- /dev/null +++ b/guide/src/documentation/index.md @@ -0,0 +1,15 @@ +# Documentation + +This section includes detailed descriptions for configuring, monitoring and using the CLI. + +--- + +## Sections +- **[Configuration](./configuration/index.md)** + * Detailed description of every parameter of Hermes. +- **[Telemetry](./telemetry/index.md)** + * Detailed description of Telemetry metrics. +- **[REST API](./rest-api.md)** + * Detailed description of the REST API. +- **[Commands Reference](./commands/index.md)** + * Detailed description of every command of Hermes. diff --git a/guide/src/rest-api.md b/guide/src/documentation/rest-api.md similarity index 94% rename from guide/src/rest-api.md rename to guide/src/documentation/rest-api.md index 68da0ce138..6dada2fd1b 100644 --- a/guide/src/rest-api.md +++ b/guide/src/documentation/rest-api.md @@ -20,8 +20,6 @@ host = '127.0.0.1' port = 3000 ``` -Please see the [relevant section in the *Configuration* page](./config.md#rest) for details about the configuration options. - ## Endpoints ### GET `/version` @@ -39,7 +37,7 @@ as the version of the REST server itself (under the `ibc-relayer-rest` key). [ { "name": "ibc-relayer", - "version": "v1.0.0" + "version": "{{#template ../templates/version}}" }, { "name": "ibc-relayer-rest", @@ -73,7 +71,7 @@ information about each chain's configuration. See the next section for more deta ### GET `/chain/:id` This endpoint returns the configuration of the chain with the given identifier, -where `:id` stands for the identififer. +where `:id` stands for the identifier. **Example** diff --git a/guide/src/telemetry.md b/guide/src/documentation/telemetry/index.md similarity index 80% rename from guide/src/telemetry.md rename to guide/src/documentation/telemetry/index.md index 73dc2db5ca..01996a99da 100644 --- a/guide/src/telemetry.md +++ b/guide/src/documentation/telemetry/index.md @@ -7,10 +7,6 @@ whose metrics can be exposed over HTTP for integration with the [Prometheus][pro The official Hermes builds for Linux and macOS come with telemetry support since version `v0.4.0`. See the [installation instructions][installation] for how to obtain the latest version of Hermes. -[installation]: installation.md#install-the-relayer -[opentelemetry]: https://opentelemetry.io -[prometheus]: https://prometheus.io - ## Configuration The telemetry service is not active by default, and must be enabled in the relayer configuration: @@ -22,4 +18,8 @@ host = '127.0.0.1' # default value port = 3001 # default value ``` -Please see the [relevant section for *Configuration*](./config.md) for more general details about Hermes configuration options. +Please see the [relevant section for *Configuration*](../configuration/index.md) for more general details about Hermes configuration options. + +[installation]: ../../quick-start/installation.md#install-the-relayer +[opentelemetry]: https://opentelemetry.io +[prometheus]: https://prometheus.io diff --git a/guide/src/telemetry/integration.md b/guide/src/documentation/telemetry/integration.md similarity index 100% rename from guide/src/telemetry/integration.md rename to guide/src/documentation/telemetry/integration.md diff --git a/guide/src/telemetry/operators.md b/guide/src/documentation/telemetry/operators.md similarity index 96% rename from guide/src/telemetry/operators.md rename to guide/src/documentation/telemetry/operators.md index 59c9845340..cd038553ea 100644 --- a/guide/src/telemetry/operators.md +++ b/guide/src/documentation/telemetry/operators.md @@ -12,21 +12,21 @@ Metrics are automatically reset if the service is restarted. ## Table of Contents -Hermes metrics are designed to be able to answer four basic questions: +Hermes' metrics are designed to be able to answer four basic questions: 1. Is Hermes active (i.e., *submitting* any transactions to any network)? 2. Are Hermes transactions successful (i.e., *confirmed* and included in the network)? 3. What is the overall IBC status of each network? -4. How efficient and how secure is the IBC status on each network? +4. How efficient, and how secure is the IBC status on each network? -For each of this question, there is a dedicated sub-section: +For each of this question, there is a dedicated subsection: ## Is Hermes active? -By _active_ we mean specifically: is Hermes *submitting* any transactions to any network? +By _active_, we mean specifically: is Hermes *submitting* any transactions to any network? The metrics in the table below are design to answer this question on multiple dimensions. | Name | Description | OpenTelemetry type | Configuration Dependencies | @@ -67,8 +67,8 @@ Importantly, these metrics are only displayed if the configuration `tx_confirmat | Name | Description | OpenTelemetry type | Configuration Dependencies | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | -------------------------- | | `tx_latency_confirmed` | Latency for all transactions confirmed by a chain | `u64` ValueRecorder | Transaction confirmation enabled | -| `receive_packets_confirmed` | Number of confirmed receive packets, per chain, channel and port | `u64` Counter | Packet workers enabled and Transaction confirmation enabled | -| `acknowledgment_packets_confirmed` | Number of confirmed acknowledgment packets, per chain, channel and port | `u64` Counter | Packet workers enabled and Transaction confirmation enabled | +| `receive_packets_confirmed` | Number of confirmed receive packets, per chain, channel and port | `u64` Counter | Packet workers enabled, and Transaction confirmation enabled | +| `acknowledgment_packets_confirmed` | Number of confirmed acknowledgment packets, per chain, channel and port | `u64` Counter | Packet workers enabled, and Transaction confirmation enabled | | `timeout_packets_confirmed` | Number of confirmed timeout packets, per chain, channel and port | `u64` Counter | Packet workers enabled and Transaction confirmation enabled | **How do we define the latency of a confirmed transaction?** diff --git a/guide/src/features.md b/guide/src/features.md deleted file mode 100644 index bf3a9acd94..0000000000 --- a/guide/src/features.md +++ /dev/null @@ -1,58 +0,0 @@ -# Features - -This section includes a summary of the supported and planned features. -A feature matrix and comparison between the Rust and Go relayer implementations can be found in the [Feature Matrix](./features/matrix.md) - -> **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. - -[ibcv1-proto]: https://github.com/cosmos/ibc - -## 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 - - 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 \ No newline at end of file diff --git a/guide/src/getting_started.md b/guide/src/getting_started.md deleted file mode 100644 index 0c1f747fbd..0000000000 --- a/guide/src/getting_started.md +++ /dev/null @@ -1,13 +0,0 @@ -# Getting Started - -In order to run Hermes, please make sure you have all the -[pre-requisites](./pre_requisites.md) installed on your machine. - -Once you have these pre-requisites, you can -[build and run Hermes](./installation.md). - -> The instructions in this guide have been tested on `Linux` and `MacOS` -> environments. Most of the commands should work on both environments. Even -> though you can build and run the relayer on `Windows` (since we develop it -> in Rust and it supports cross platform compilation) we have not tested the -> relayer on `Windows` and we do not support this operating system at this time. \ No newline at end of file diff --git a/guide/src/glossary.md b/guide/src/glossary.md index bd5d914486..e5fadfa233 100644 --- a/guide/src/glossary.md +++ b/guide/src/glossary.md @@ -1,6 +1,6 @@ # Glossary -These are some of the definitions used in this guide: +These are some definitions used in this guide: | Term | Definition | |------|------------| diff --git a/guide/src/help.md b/guide/src/help.md deleted file mode 100644 index 738e258f22..0000000000 --- a/guide/src/help.md +++ /dev/null @@ -1,647 +0,0 @@ -# Help - -This section provides guidelines regarding troubleshooting and general -resources for getting help with `hermes`. -For this purpose, we recommend a few ideas that could be of help: - -- [hermes help][help] command, providing a CLI - documentation for all `hermes` commands. -- [profile][profiling] your relayer binary to identify slow methods; -- [configure][log-level] the `log_level` to help with debugging; -- [patch][patching] your local gaia chain(s) to enable some corner-case methods - (e.g., channel close); - -And if the above options do not address your specific problem: -- you can [request a new feature][feature]; -- or consult the [list of reported issues][issues] and search by relevant - keywords to see if you're dealing with a known problem; -- we would be grateful if you can submit a [bug report][bug-report] - discussing any problem you find, and from there on we can look at the - problem together; - -Lastly, for general questions, you can reach us at `hello@informal.systems`, -or on Twitter [@informalinc][twitter]. - -## Table of contents - - - -## 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 - -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-connection --a-port --b-port - - hermes create channel [OPTIONS] --a-chain --b-chain --a-port --b-port --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 - 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 - The channel ordering, valid options 'unordered' (default) and 'ordered' - - [default: ORDER_UNORDERED] - - --yes - Skip new_client_connection confirmation - -FLAGS: - --a-chain - Identifier of the side `a` chain for the new channel - - --a-connection - Identifier of the connection on chain `a` to use in creating the new channel - - [aliases: a-conn] - - --a-port - Identifier of the side `a` port for the new channel - - --b-chain - Identifier of the side `b` chain for the new channel - - --b-port - Identifier of the side `b` port for the new channel -``` - -Additionally, the `-h`/`--help` flags typical for CLI applications work on -all commands. - -## Parametrizing the log output level - -The relayer configuration file permits parametrization of output verbosity via the knob called `log_level`. -This file is loaded by default from `$HOME/.hermes/config.toml`, but can be overridden in all commands -with the `--config` flag, eg. `hermes --config ./path/to/my/config.toml some command`. - -Relevant snippet: - -```toml -[global] -log_level = 'error' -``` - -Valid options for `log_level` are: 'error', 'warn', 'info', 'debug', 'trace'. -These levels correspond to the tracing sub-component of the relayer-cli, -[see here](https://docs.rs/tracing-core/0.1.17/tracing_core/struct.Level.html). - -The relayer will _always_ print a last line summarizing the result of its -operation for queries or transactions. In addition to this last line, -arbitrary debug, info, or other outputs may be produced. - -## Overriding the tracing filter using `RUST_LOG` - -For debugging purposes, we may want to inspect which RPC queries the relayer is making. -The relayer makes use of the `tendermint-rpc` library to issue RPC queries, but -the output of this library is by default turned off in order to keep the logs more -readable. - -Using the `RUST_LOG` environment variable, we can turn logging on for the -`tendermint-rpc` library, as follows: - -``` -RUST_LOG=tendermint-rpc=debug,info hermes start -``` - -Setting the `RUST_LOG` environment variable to `tendermint_rpc=debug,info` instructs -the relayer to set the log level of the `tendermint_rpc` crate to `debug` and otherwise -use the `info` log level. - -> **Note:** While the `tendermint-rpc` contains a dash in its name, the logging filter -> expects a module name, which can only contain alphanumeric characters and underscores, -> hence why the filter above is written `tendermint_rpc=debug`. - -**Example:** - -``` -❯ RUST_LOG=tendermint_rpc=debug,info hermes start -2022-02-24T14:32:14.039555Z INFO ThreadId(01) using default configuration from '/Users/coromac/.hermes/config.toml' -2022-02-24T14:32:14.043500Z INFO ThreadId(01) telemetry service running, exposing metrics at http://127.0.0.1:3001/metrics -2022-02-24T14:32:14.043542Z INFO ThreadId(01) [rest] address not configured, REST server disabled -2022-02-24T14:32:14.049759Z DEBUG ThreadId(01) Incoming response: { - "jsonrpc": "2.0", - "id": "143b4580-c49e-47c1-81b2-4e7090f6e762", - "result": { - "node_info": { - "protocol_version": { - "p2p": "8", - "block": "11", - "app": "0" - }, - "id": "73f9134539f9845cd253dc302e36d48ee4c0f32d", - "listen_addr": "tcp://0.0.0.0:27003", - "network": "ibc0", - "version": "v0.34.14", - "channels": "40202122233038606100", - "moniker": "ibc0", - "other": { - "tx_index": "on", - "rpc_address": "tcp://0.0.0.0:27000" - } - }, - "sync_info": { - "latest_block_hash": "8396B93E355AD80EED8167A04BB9858A315A8BEB482547DE16A6CD82BC11551B", - "latest_app_hash": "22419E041D6997EE75FF66F7F537A3D36122B220EAB89A9C246FEF680FB1C97A", - "latest_block_height": "86392", - "latest_block_time": "2022-02-24T14:32:08.673989Z", - "earliest_block_hash": "0A73CFE8566D4D4FBFE3178D9BCBAD483FD689854CA8012FF1457F8EC4598132", - "earliest_app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "earliest_block_height": "1", - "earliest_block_time": "2022-01-20T09:04:21.549736Z", - "catching_up": false - }, - "validator_info": { - "address": "6FD56E6AA1EEDAD227AFAB6B9DE631719D4A3691", - "pub_key": { - "type": "tendermint/PubKeyEd25519", - "value": "mR5V/QWOv/mJYyNmlsl3mfxKy1PNaOzdztyas4NF2BA=" - }, - "voting_power": "10" - } - } -} -2022-02-24T14:32:14.052503Z DEBUG ThreadId(21) Incoming response: { - "jsonrpc": "2.0", - "id": "0ca35e64-ea98-4fbf-bd66-c3291128ace9", - "result": {} -} - -... -``` - -The two DEBUG log lines above were emitted by the `tendermint-rpc` crate. - -## Inspecting the relayer state - -To get a little bit of insight into the state of the relayer, -Hermes will react to a `SIGUSR1` signal by dumping its state to -the console, either in plain text form or as a JSON object if Hermes -was started with the `--json` option. - -To send a `SIGUSR1` signal to Hermes, look up its process ID (below PID) -and use the following command: - -```shell -kill -SIGUSR1 PID -``` - -Hermes will print some information about the workers which are currently running. - -For example, with three chains configured and one channel between each pair of chains: - -```text -INFO Dumping state (triggered by SIGUSR1) -INFO -INFO * Chains: ibc-0, ibc-1, ibc-2 -INFO * Client workers: -INFO - client::ibc-0->ibc-1:07-tendermint-0 (id: 5) -INFO - client::ibc-0->ibc-2:07-tendermint-0 (id: 9) -INFO - client::ibc-1->ibc-0:07-tendermint-0 (id: 1) -INFO - client::ibc-1->ibc-2:07-tendermint-1 (id: 11) -INFO - client::ibc-2->ibc-0:07-tendermint-1 (id: 3) -INFO - client::ibc-2->ibc-1:07-tendermint-1 (id: 7) -INFO * Packet workers: -INFO - packet::channel-0/transfer:ibc-0->ibc-1 (id: 2) -INFO - packet::channel-0/transfer:ibc-1->ibc-0 (id: 6) -INFO - packet::channel-0/transfer:ibc-2->ibc-0 (id: 10) -INFO - packet::channel-1/transfer:ibc-0->ibc-2 (id: 4) -INFO - packet::channel-1/transfer:ibc-1->ibc-2 (id: 8) -INFO - packet::channel-1/transfer:ibc-2->ibc-1 (id: 12) -``` - -or in JSON form (prettified): - -```json -{ - "timestamp": "Jul 12 17:04:37.244", - "level": "INFO", - "fields": { - "message": "Dumping state (triggered by SIGUSR1)" - } -} -{ - "chains": [ - "ibc-0", - "ibc-1", - "ibc-2" - ], - "workers": { - "Client": [ - { - "id": 5, - "object": { - "type": "Client", - "dst_chain_id": "ibc-1", - "dst_client_id": "07-tendermint-0", - "src_chain_id": "ibc-0" - } - }, - { - "id": 9, - "object": { - "type": "Client", - "dst_chain_id": "ibc-2", - "dst_client_id": "07-tendermint-0", - "src_chain_id": "ibc-0" - } - }, - { - "id": 1, - "object": { - "type": "Client", - "dst_chain_id": "ibc-0", - "dst_client_id": "07-tendermint-0", - "src_chain_id": "ibc-1" - } - }, - { - "id": 11, - "object": { - "type": "Client", - "dst_chain_id": "ibc-2", - "dst_client_id": "07-tendermint-1", - "src_chain_id": "ibc-1" - } - }, - { - "id": 3, - "object": { - "type": "Client", - "dst_chain_id": "ibc-0", - "dst_client_id": "07-tendermint-1", - "src_chain_id": "ibc-2" - } - }, - { - "id": 7, - "object": { - "type": "Client", - "dst_chain_id": "ibc-1", - "dst_client_id": "07-tendermint-1", - "src_chain_id": "ibc-2" - } - } - ], - "Packet": [ - { - "id": 2, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-1", - "src_chain_id": "ibc-0", - "src_channel_id": "channel-0", - "src_port_id": "transfer" - } - }, - { - "id": 6, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-0", - "src_chain_id": "ibc-1", - "src_channel_id": "channel-0", - "src_port_id": "transfer" - } - }, - { - "id": 10, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-0", - "src_chain_id": "ibc-2", - "src_channel_id": "channel-0", - "src_port_id": "transfer" - } - }, - { - "id": 4, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-2", - "src_chain_id": "ibc-0", - "src_channel_id": "channel-1", - "src_port_id": "transfer" - } - }, - { - "id": 8, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-2", - "src_chain_id": "ibc-1", - "src_channel_id": "channel-1", - "src_port_id": "transfer" - } - }, - { - "id": 12, - "object": { - "type": "Packet", - "dst_chain_id": "ibc-1", - "src_chain_id": "ibc-2", - "src_channel_id": "channel-1", - "src_port_id": "transfer" - } - } - ] - } -} -``` - -## Connecting to a full node protected by HTTP Basic Authentication - -To connect to a full node protected by [HTTP Basic Authentication][http-basic-auth], -specify the username and password in the `rpc_addr`, `grpc_addr` and `websocket_addr` settings -under the chain configuration in `config.toml`. - -Here is an example with username `hello` and password `world`, assuming the RPC, WebSocket and gRPC servers -listen on domain `mydomain.com` with TLS enabled (HTTPS/WSS). - -```toml -[[chains]] -id = 'my-chain-0' - -# ... - -rpc_addr = 'https://hello:world@mydomain.com:26657' -grpc_addr = 'https://hello:world@mydomain.com:9090' -websocket_addr = 'wss://hello:world@mydomain.com:26657/websocket' - -# ... -``` - -> **Caution:** Warning: The "Basic" authentication scheme sends the credentials encoded but not encrypted. -> This would be completely insecure unless the exchange was over a secure connection (HTTPS/TLS). - -[http-basic-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication - -## Patching `gaia` to support `ChanCloseInit` - -The guide below refers specifically to patching your gaia chain so that the -relayer can initiate the closing of channels by submitting a [`ChanCloseInit`][chan-close] message. -Without this modification, the transaction will be rejected. -We also describe how to test the channel closing feature. - -- Clone the Cosmos SDK - - ```shell - git clone https://github.com/cosmos/cosmos-sdk.git ~/go/src/github.com/cosmos/cosmos-sdk - cd ~/go/src/github.com/cosmos/cosmos-sdk - ``` - -- Apply these diffs: - - ``` - --- a/x/ibc/applications/transfer/module.go - +++ b/x/ibc/applications/transfer/module.go - @@ -305,7 +305,7 @@ func (am AppModule) OnChanCloseInit( - channelID string, - ) error { - // Disallow user-initiated channel closing for transfer channels - - return sdkerrors.Wrap(sdkerrors.ErrInvalidRequest, "user cannot close channel") - + return nil - } - ``` - -- Append the line below (watch for the placeholder ``) as the last line - in your `go.mod` in the gaia clone: - -```replace github.com/cosmos/cosmos-sdk => /Users//go/src/github.com/cosmos/cosmos-sdk``` - -- Now `make build` and `make install` your local copy of gaia - -In order to test the correct operation during the channel close, perform the steps below. - -- the channel should be in state open-open: - -- transfer of 5555 samoleans from `ibc-1` to `ibc-0`. This results in a - Tx to `ibc-1` for a `MsgTransfer` packet. - Make sure you're not relaying this packet (the relayer should not be running on - this path). - - ```shell - hermes tx ft-transfer --receiver-chain ibc-0 --sender-chain ibc-1 --sender-port transfer --sender-channel channel-1 --amount 5555 --timeout-height-offset 1000 --number-msgs 1 --denom samoleans - ``` - -- now do the first step of channel closing: the channel will transition -to close-open: - - ```shell - hermes --config config.toml tx chan-close-init --receiver-chain ibc-0 --sender-chain ibc-1 --receiver-connection connection-0 --receiver-port transfer --sender-port transfer --receiver-channel channel-0 --sender-channel channel-1 - ``` - -- trigger timeout on close to ibc-1 - - ```shell - hermes --config config.toml tx packet-recv --receiver-chain ibc-0 --sender-chain ibc-1 --sender-port transfer --sender-channel channel-1 - ``` - -- close-close - - ```shell - hermes --config config.toml tx chan-close-confirm --receiver-chain ibc-1 --sender-chain ibc-0 --receiver-connection connection-1 --receiver-port transfer --sender-port transfer --receiver-channel channel-1 --sender-channel channel-0 - ``` - -- verify that the two ends are in Close state: - - ```shell - hermes --config config.toml query channel end --chain ibc-0 --port transfer --channel channel-0 - hermes --config config.toml query channel end --chain ibc-1 --port transfer --channel channel-1 - ``` - - -## New Feature Request - -If you would like a feature to be added to `hermes`, don't hesitate -to open a discussion about that via the [feature request][feature-request] -issue template. - -> Note that Hermes is packaged as part of the `ibc-relayer-cli` crate. - - -## Profiling - -The `relayer` crate provides a `time!` macro which can be used to measure how much time is spent between the invocation of the macro and the end of the enclosing scope. - -### Setup - -The `time!` macro has no effect unless the `profiling` feature of the `relayer` crate is enabled. - -To enable it, one must compile the `relayer-cli` crate with the `--features=profiling` flag. - -a) One way is to build the `relayer` binary and update the `hermes` alias to point to the executable: - -```shell -cd relayer-cli/ -cargo build --features=profiling -``` - -b) Alternatively, one can use the `cargo run` command and update the alias accordingly: - -```shell -alias hermes='cargo run --features=profiling --manifest-path=relayer-cli/Cargo.toml --' -``` - -The `--manifest-path=relayer-cli/Cargo.toml` flag is needed for `cargo run` to accept the `--features` flag. - -### Example - -```rust -fn my_function(x: u32) -> u32 { - time!("myfunction: x={}", x); // A - - std::thread::sleep(Duration::from_secs(1)); - - { - time!("inner operation"); // B - - std::thread::sleep(Duration::from_secs(2)); - - // timer B ends here - } - - x + 1 - - // timer A ends here -} -``` - -#### Output - -``` -Jan 20 11:28:46.841 INFO relayer::macros::profiling: ⏳ myfunction: x=42 - start -Jan 20 11:28:47.842 INFO relayer::macros::profiling: ⏳ inner operation - start -Jan 20 11:28:49.846 INFO relayer::macros::profiling: ⏳ inner operation - elapsed: 2004ms -Jan 20 11:28:49.847 INFO relayer::macros::profiling: ⏳ myfunction: x=42 - elapsed: 3005ms -``` - -Profiling is useful for tracking down unusually slow methods. -Each transaction or query usually consists of multiple lower-level methods, -and it's often not clear which of these are the culprit for low performance. -With profiling enabled, `hermes` will output timing information for individual -methods involved in a command. - -__NOTE__: To be able to see the profiling output, the realyer needs to be compiled with -the `profiling` feature and the [log level][log-level] should be `info` level or lower. - -#### Example output for `tx conn-init` command - -``` -hermes --config config.toml tx conn-init --b-chain ibc-0 --a-chain ibc-1 --b-client 07-tendermint-0 --a-client 07-tendermint-0 -``` - -``` -Apr 13 20:58:21.225 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - start -Apr 13 20:58:21.230 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - elapsed: 4ms -Apr 13 20:58:21.230 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - start -Apr 13 20:58:21.235 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - elapsed: 5ms -Apr 13 20:58:21.235 INFO ibc_relayer::event::monitor: running listener chain.id=ibc-1 -Apr 13 20:58:21.236 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - start -Apr 13 20:58:21.239 INFO ibc_relayer::macros::profiling: ⏳ init_light_client - elapsed: 2ms -Apr 13 20:58:21.239 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - start -Apr 13 20:58:21.244 INFO ibc_relayer::macros::profiling: ⏳ init_event_monitor - elapsed: 4ms -Apr 13 20:58:21.244 INFO ibc_relayer::event::monitor: running listener chain.id=ibc-0 -Apr 13 20:58:21.244 INFO ibc_relayer::macros::profiling: ⏳ get_signer - start -Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ get_signer - elapsed: 1ms -Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ query_latest_height - start -Apr 13 20:58:21.246 INFO ibc_relayer::macros::profiling: ⏳ block_on - start -Apr 13 20:58:21.248 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 1ms -Apr 13 20:58:21.249 INFO ibc_relayer::macros::profiling: ⏳ query_latest_height - elapsed: 3ms -Apr 13 20:58:21.250 INFO ibc_relayer::macros::profiling: ⏳ unbonding_period - start -Apr 13 20:58:21.250 INFO ibc_relayer::macros::profiling: ⏳ block_on - start -Apr 13 20:58:21.251 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 0ms -Apr 13 20:58:21.270 INFO ibc_relayer::macros::profiling: ⏳ block_on - start -Apr 13 20:58:21.273 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 2ms -Apr 13 20:58:21.273 INFO ibc_relayer::macros::profiling: ⏳ unbonding_period - elapsed: 23ms -Apr 13 20:58:21.279 INFO ibc_relayer::macros::profiling: ⏳ build_consensus_state - start -Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ build_consensus_state - elapsed: 0ms -Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ send_msgs - start -Apr 13 20:58:21.280 INFO ibc_relayer::macros::profiling: ⏳ send_tx - start -Apr 13 20:58:21.282 INFO ibc_relayer::macros::profiling: ⏳ PK "03f17d2c094ee68cfcedb2c2f2b7dec6cd82ea158ac1c32d3de0ca8b288a3c8bfa" - start -Apr 13 20:58:21.282 INFO ibc_relayer::macros::profiling: ⏳ block_on - start -Apr 13 20:58:21.285 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 3ms -Apr 13 20:58:21.296 INFO ibc_relayer::macros::profiling: ⏳ block_on - start -Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ block_on - elapsed: 1367ms -Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ PK "03f17d2c094ee68cfcedb2c2f2b7dec6cd82ea158ac1c32d3de0ca8b288a3c8bfa" - elapsed: 1382ms -Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ send_tx - elapsed: 1384ms -Apr 13 20:58:22.664 INFO ibc_relayer::macros::profiling: ⏳ send_msgs - elapsed: 1384ms -Success: CreateClient( - CreateClient( - Attributes { - height: Height { - revision: 0, - height: 10675, - }, - client_id: ClientId( - "07-tendermint-7", - ), - client_type: Tendermint, - consensus_height: Height { - revision: 1, - height: 10663, - }, - }, - ), -) -``` - - - -[help]: ./help.md#help-command -[feature-request]: https://github.com/informalsystems/ibc-rs/issues/new?assignees=&labels=&template=feature-request.md -[bug-report]: https://github.com/informalsystems/ibc-rs/issues/new?assignees=&labels=&template=bug-report.md -[twitter]: https://twitter.com/informalinc -[twitter-image]: https://abs.twimg.com/errors/logo23x19.png -[website]: https://informal.systems -[log-level]: ./help.md#parametrizing-the-log-output-level -[issues]: https://github.com/informalsystems/ibc-rs/issues -[profiling]: ./help.md#profiling -[feature]: ./help.md#new-feature-request -[patching]: ./help.md#patching-gaia -[chan-close]: ./commands/tx/channel-close.md#channel-close-init diff --git a/guide/src/index.md b/guide/src/index.md index 84fa804cfe..14d80e5794 100644 --- a/guide/src/index.md +++ b/guide/src/index.md @@ -1,53 +1,105 @@ -# Hermes Guide (v1.0.0) +# Hermes Guide ({{#template templates/version}}) +## Overview -Hermes is a an open-source Rust implementation of a relayer for the -[Inter-Blockchain Communication protocol](https://ibcprotocol.org) (IBC). +Hermes is an open-source Rust implementation of a relayer for the +[Inter-Blockchain Communication protocol](https://ibc.cosmos.network) (**IBC**) released under the [ibc-relayer-cli](https://crates.io/crates/ibc-relayer-cli) crate. It provides a CLI to relay packets between Cosmos SDK chains, exposes [Prometheus](https://prometheus.io/) metrics and offers a REST API. -This guide can help you setup, configure, and operate Hermes to transfer +This guide can help you set up, configure, operate and monitor Hermes to relay packets between two or more IBC-enabled chains. -## Sections +## About Hermes -**[What is Hermes](./relayer.md)** +An IBC relayer is an off-chain process responsible for relaying IBC datagrams between any two chains. The way it does so is by scanning chain states, building transactions based on these states, and submitting the transactions to the chains involved in the network. -- Explains what Hermes is about. +The relayer is a central element in the IBC network architecture. This is because chain modules in this architecture are not directly sending messages to each other over networking infrastructure, but instead they create and store the data to be retrieved and used by a relayer to build the IBC datagrams. -**[Features](./features.md)** +We sometimes refer to Hermes as "IBC Relayer CLI", to make it clear that this is a relayer CLI (i.e., a binary) and distinguish it from the relayer core library (that is the crate called ibc-relayer). -- This section discusses what features to expect from Hermes, as well as a - comparison between the Cosmos Go relayer and Hermes. +Hermes is actively developed and maintained by [Informal Systems](https://informal.systems) in the [ibc-rs](https://github.com/informalsystems/ibc-rs) repository. -**[Getting Started](./getting_started.md)** +## Where to go -- The getting started section can help you setup, configure, and run Hermes. +* **[Glossary](./glossary.md)** -**[Tutorials](./tutorials/index.md)** + - This section provides some definitions of terms used throughout the guide. -- This section provides some tutorials on how to operate and test Hermes. -**[Commands Reference](./commands/index.md)** +* **[Quick start](./quick-start/index.md)** -- The commands let you interact with Hermes using its command line interface. + - This section can help you install Hermes. -**[Help](./help.md)** +* **[Tutorials](./tutorials/index.md)** -- This part provides guidelines regarding troubleshooting and general resources - for getting help. + - **[Prerequisites for local chains](./tutorials/local-chains/index.md)** + - Install `Gaia` and `gm` (Gaia Manager) for tutorials using local chains. + - **[Two Local Chains](./tutorials/local-chains/index.md)** + - Start two local [`Cosmos Gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol and learn the fundamentals of IBC. + - **[More Local Chains](./tutorials/more-chains/index.md)** + - Learn how to relay on an arbitrary topology of more than two chains by using packet filters and to run multiple instances of Hermes. + - **[Relaying in production](./tutorials/production/index.md)** + - Learn how to set up, configure and run `hermes` on IBC-enabled chains in production. -**[Glossary](./glossary.md)** +* **[Advanced](./advanced/index.md)** + - **[Features](./advanced/features.md)** + - This section summarizes Hermes' features and includes a comparison between the Cosmos Go relayer and Hermes. + - **[Troubleshooting](./advanced/troubleshooting/index.md)** + - Learn the general guidelines regarding troubleshooting. + + +* **[Documentation](./documentation/index.md)** + - **[Configuration](./documentation/configuration/index.md)** + - This section includes everything you need to know to configure Hermes. + - **[Telemetry](./documentation/telemetry/index.md)** + - This section describes all Prometheus metrics and how to use them efficiently. + - **[REST API](./documentation/rest-api.md)** + - This section presents Hermes' REST API. + - **[Commands Reference](./documentation/commands/index.md)** + - This section describes the command line interface from which you can interact with Hermes. + +* Educational resources + - [About IBC](https://ibc.cosmos.network/) + - The official IBC-Go documentation. + - [Cosmos network tutorial](https://tutorials.cosmos.network/academy/4-ibc/what-is-ibc.html#) + - Learn the basics of IBC in the official tutorial. + - [Connect IBC enabled chains with Hermes](https://www.youtube.com/watch?v=_xQDTj1PcEw&t=4289s) + - Video demonstration of Hermes at Hackatom 2021. + +* Useful links + - [Hermes FAQ Page](https://github.com/informalsystems/ibc-rs/discussions/2472) + - The official FAQ of Hermes. + - [Hermes GitHub repository](https://github.com/informalsystems/ibc-rs) + - The official GitHub repository for Hermes. + - [IBC GitHub repository](https://github.com/cosmos/ics) + - The official repository for the Inter-blockchain protocol (IBC). + - [IBC Protocol](https://ibcprotocol.org) + - The official IBC protocol page. + +## Contact + +- Request a [new feature](#new-feature-request) via the [feature request][feature-request] issue template; +- Consult the [list of reported issues][issues] and search by relevant + keywords to see if you're dealing with a known problem; +- We would be grateful if you can submit a [bug report][bug-report] + discussing any problem you find, and from there on we can look at the + problem together; +- Reach Hermes developpers and other relayer operators on the [Cosmos Network Discord server](https://discord.com/invite/cosmosnetwork). + +Lastly, for general questions, you can reach us at `hello@informal.systems`, +or on Twitter [@informalinc][twitter]. + +> Note that Hermes is packaged as part of the `ibc-relayer-cli` crate. -- This section provides some definitions of terms used throughout the guide --- -**Other References and Useful Links:** +__Disclaimer__ This project is undergoing heavy development, use at your own risk. + +--- -* [Hermes Github repository](https://github.com/informalsystems/ibc-rs) - — The official Github repository for Hermes. -* [IBC Github repository](https://github.com/cosmos/ics) - - The official repository for the Inter-blockchain protocol (IBC). -## Disclaimer -This project is undergoing heavy development, use at your own risk. +[feature-request]: https://github.com/informalsystems/ibc-rs/issues/new?assignees=&labels=&template=feature-request.md +[bug-report]: https://github.com/informalsystems/ibc-rs/issues/new?assignees=&labels=&template=bug-report.md +[twitter]: https://twitter.com/informalinc +[issues]: https://github.com/informalsystems/ibc-rs/issues \ No newline at end of file diff --git a/guide/src/quick-start/index.md b/guide/src/quick-start/index.md new file mode 100644 index 0000000000..327abfdd40 --- /dev/null +++ b/guide/src/quick-start/index.md @@ -0,0 +1,19 @@ +# Quick Start + +In order to run Hermes, please make sure you have all the +[prerequisites](./pre-requisites.md) installed on your machine. + +Once you have these prerequisites, you can +[build and run Hermes](./installation.md). + +> The instructions in this guide have been tested on `Linux` and `MacOS` +> environments. Most of the commands should work on both environments. It is +> currently impossible to build and run `Hermes` on `Windows`. + +--- + +## Sections +- **[Prerequisites](./pre-requisites.md)** + * Install the latest versions of `Rust` and `Golang`. +- **[Installation](./installation.md)** + * Install Hermes. diff --git a/guide/src/installation.md b/guide/src/quick-start/installation.md similarity index 76% rename from guide/src/installation.md rename to guide/src/quick-start/installation.md index ab4f27abc4..faee2fbdf2 100644 --- a/guide/src/installation.md +++ b/guide/src/quick-start/installation.md @@ -1,9 +1,9 @@ -# Install the relayer +# Install Hermes There are two main approaches for obtaining Hermes: 1. Installation: - 1. If you are running on a Unix machine (Linux/MacOS), then the simplest + 1. If you are running on a Unix machine (Linux/macOS), then the simplest option is to [download the latest binary](#install-by-downloading). 2. You can also install via [Cargo](#install-via-cargo). @@ -14,8 +14,8 @@ There are two main approaches for obtaining Hermes: Simply head to the GitHub [Releases][releases] page and download the latest version of Hermes binary matching your platform: -- MacOS: `hermes-v1.0.0-x86_64-apple-darwin.tar.gz` (or .zip), -- Linux: `hermes-v1.0.0-x86_64-unknown-linux-gnu.tar.gz` (or .zip). +- macOS: `hermes-{{#template ../templates/version}}-x86_64-apple-darwin.tar.gz` (or .zip), +- Linux: `hermes-{{#template ../templates/version}}-x86_64-unknown-linux-gnu.tar.gz` (or .zip). The step-by-step instruction below should carry you through the whole process: @@ -36,24 +36,26 @@ The step-by-step instruction below should carry you through the whole process: ``` > NOTE: The binary may be initially prevented from running if you're -> on MacOS. +> on macOS. > See the ["Open Anyway" instructions from this support forum][developer-app] > if that is the case. You should now be able to run Hermes by invoking the `hermes` executable. ```shell -hermes version +{{#template ../templates/commands/hermes/version}} ``` +Which should be: + ``` -hermes v1.0.0 +hermes {{#template ../templates/version}} ``` ## Install via Cargo > NOTE: This approach assumes you have installed all -> the [pre-requisites](./pre_requisites.md) on your machine. +> the [prerequisites](./pre-requisites.md) on your machine. Hermes is packaged in the `ibc-relayer-cli` Rust crate. To install the latest release of Hermes, run the following command in a terminal: @@ -77,11 +79,13 @@ This will download and build the crate `ibc-relayer-cli`, and install the You should now be able to run Hermes by invoking the `hermes` executable. ```shell -hermes version +{{#template ../templates/commands/hermes/version}} ``` +Which should be: + ``` -hermes v1.0.0 +hermes {{#template ../templates/version}} ``` ## Build from source @@ -91,7 +95,7 @@ hermes v1.0.0 Open a terminal and clone the `ibc-rs` repository: ```shell -git clone https://github.com/informalsystems/ibc-rs.git +{{#template ../templates/commands/git/clone_ibc_rs}} ``` Change to the repository directory @@ -103,10 +107,10 @@ cd ibc-rs Go to the [ibc-rs releases](https://github.com/informalsystems/ibc-rs/releases) page to see what is the most recent release. -Then checkout the release, for example if the most recent release is `v1.0.0` then execute the command: +Then checkout the release, for example if the most recent release is `{{#template ../templates/version}}` then execute the command: ```shell -git checkout v1.0.0 +git checkout {{#template ../templates/version}} ``` ### Building with `cargo build` @@ -120,7 +124,7 @@ cargo build --release --bin hermes -> By default, Hermes bundles a [telemetry service and server](./telemetry.md). +> By default, Hermes bundles a [telemetry service and server](../documentation/telemetry/index.md). > To build Hermes without telemetry support, and get a smaller executable, > supply the `--no-default-features flag` to `cargo build`: > @@ -151,7 +155,7 @@ If you run the `hermes` without any additional parameters you should see the usa ``` ``` -hermes v1.0.0 +hermes {{#template ../templates/version}} Informal Systems USAGE: @@ -182,15 +186,15 @@ SUBCOMMANDS: ### Creating an alias for the executable -It might be easier to create an alias for `hermes` so you can just run it by specifying the executable name instead of the whole path. In order to create an alias execute the following command: +It might be easier to create an alias for `hermes`, so you can just run it by specifying the executable name instead of the whole path. In order to create an alias execute the following command: ```shell -alias hermes='cargo run --release --bin hermes --' +alias hermes='cargo run --manifest-path $IBCRSPATH/Cargo.toml --release --bin hermes --' ``` ## Shell auto-completions -The `completions` subcommand of Hermes can be used to output a completion script +The `completions` sub-command of Hermes can be used to output a completion script for a choice of widely used command-line shells. Refer to `hermes completions --help` for the list. Some shell-specific examples of setting up auto-completion with this command are provided below; check your @@ -200,19 +204,19 @@ and any further necessary modifications to the shell's startup files. ### Bash ```sh -hermes completions --shell bash > ~/.local/share/bash-completion/completions/hermes +{{#template ../templates/commands/hermes/completions shell=bash}} > ~/.local/share/bash-completion/completions/hermes ``` -On a MacOS installation with Homebrew `bash-completion` formula installed, use +On a macOS installation with Homebrew `bash-completion` formula installed, use ```sh -hermes completions --shell bash > $(brew --prefix)/etc/bash_completion.d/hermes.bash-completion +{{#template ../templates/commands/hermes/completions shell=bash}} > $(brew --prefix)/etc/bash_completion.d/hermes.bash-completion ``` ### Zsh ```sh -hermes completions --shell zsh > ~/.zfunc/_hermes +{{#template ../templates/commands/hermes/completions shell=zsh}} > ~/.zfunc/_hermes ``` To make the shell load the script on initialization, add the directory to `fpath` @@ -224,8 +228,8 @@ fpath+=~/.zfunc ## Next Steps -Go to the [`Configuration`](./config.md) section to learn how to create a configuration file to be used by Hermes. +Go to the [`Tutorials`](../tutorials/index.md) section to learn the basics of Hermes. [releases]: https://github.com/informalsystems/ibc-rs/releases -[developer-app]: https://support.apple.com/en-gb/HT202491 +[developer-app]: https://support.apple.com/HT202491 diff --git a/guide/src/pre_requisites.md b/guide/src/quick-start/pre-requisites.md similarity index 65% rename from guide/src/pre_requisites.md rename to guide/src/quick-start/pre-requisites.md index 02d06077a3..215bda652d 100644 --- a/guide/src/pre_requisites.md +++ b/guide/src/quick-start/pre-requisites.md @@ -8,23 +8,23 @@ The IBC Relayer is developed with the [Rust](https://www.rust-lang.org) programm For instructions on how to install `Rust` on your machine please follow the official [`Notes about Rust Installation`](https://www.rust-lang.org/tools/install). -The provided instructions will install all the Rust toolchain including `rustc`, `cargo`, and `rustup` that are required to build the project. +The provided instructions will install all the Rust tool chain including `rustc`, `cargo`, and `rustup` that are required to build the project. ### Version requirements Hermes is developed and tested using the latest version of Rust, `1.60` at -the moment. To check that your toolchain is up-to-date run: +the moment. To check that your tool chain is up-to-date run: ```shell rustc --version ``` -In case you already had installed the Rust toolchain in the past, you can +In case you already had installed the Rust tool chain in the past, you can update your installation by running `rustup update`. ### Testing the installation -After you install the `Rust` toolchain you can execute the following command: +After you install the `Rust` tool chain you can execute the following command: ```shell cargo version @@ -34,7 +34,7 @@ This should display the `cargo` version and confirm the proper installation. ## 2. Golang -You will also need the __Go__ programming language installed and configured on your machine. This is a requirement for the the section [Installing Gaia](./tutorials/local-chains/gaia.md) in the [Two Local Chains](./tutorials/local-chains/index.md) tutorial. +You will also need the __Go__ programming language installed and configured on your machine. This is a requirement for the section [Installing Gaia](../tutorials/pre-requisites/gaia.md). To install and configure Golang on your machine please follow the [Golang official documentation](https://golang.org/doc/install). diff --git a/guide/src/relayer.md b/guide/src/relayer.md deleted file mode 100644 index 8e8a538c34..0000000000 --- a/guide/src/relayer.md +++ /dev/null @@ -1,25 +0,0 @@ -# What is Hermes? - -Hermes is an open-source Rust implementation of a relayer for the -[Inter-Blockchain Communication protocol](https://ibc.cosmos.network) (IBC), -released under the [ibc-relayer-cli](https://crates.io/crates/ibc-relayer-cli) crate. - -The **Inter-Blockchain Communication protocol** is an end-to-end, connection-oriented, -stateful protocol for reliable, ordered, and authenticated communication between modules -on separate distributed ledgers. [^ibc] - -An IBC **relayer** is an off-chain process responsible for relaying IBC messages between any two chains. -The way it does so is by scanning chain states, building transactions based on these states, -and submitting the transactions to the chains involved in the network. - -The relayer is a central element in the IBC network architecture. This is because chain modules -in this architecture are not directly sending messages to each other over networking infrastructure, -but instead they create and store the data to be retrieved and used by a relayer to build the IBC messages. - -We sometimes refer to Hermes as "IBC Relayer CLI", to make it clear that this -is a relayer CLI (i.e., a binary) and distinguish it from the relayer core library -(that is the crate called [`ibc-relayer`](https://crates.io/crates/ibc-relayer)). - -Hermes is actively developed and maintained by [Informal Systems](https://informal.systems) in the [ibc-rs](https://github.com/informalsystems/ibc-rs) repository. - -[^ibc]: [The Interblockchain Communication Protocol: An Overview](https://arxiv.org/pdf/2006.15918.pdf) diff --git a/guide/src/templates/commands/gaia/query_balances b/guide/src/templates/commands/gaia/query_balances new file mode 100644 index 0000000000..7ace1835eb --- /dev/null +++ b/guide/src/templates/commands/gaia/query_balances @@ -0,0 +1 @@ +gaiad --node [[#node]] query bank balances $(gaiad --home [[#home]] keys --keyring-backend="test" show [[#wallet]] -a) \ No newline at end of file diff --git a/guide/src/templates/commands/gaia/version b/guide/src/templates/commands/gaia/version new file mode 100644 index 0000000000..9dd1821cfe --- /dev/null +++ b/guide/src/templates/commands/gaia/version @@ -0,0 +1 @@ +gaiad version --log_level error --long | head -n4 \ No newline at end of file diff --git a/guide/src/templates/commands/git/clone_ibc_rs b/guide/src/templates/commands/git/clone_ibc_rs new file mode 100644 index 0000000000..911aad0c70 --- /dev/null +++ b/guide/src/templates/commands/git/clone_ibc_rs @@ -0,0 +1 @@ +git clone https://github.com/informalsystems/ibc-rs.git \ No newline at end of file diff --git a/guide/src/templates/commands/git/gaia b/guide/src/templates/commands/git/gaia new file mode 100644 index 0000000000..0ca44281cf --- /dev/null +++ b/guide/src/templates/commands/git/gaia @@ -0,0 +1 @@ +git clone https://github.com/cosmos/gaia.git \ No newline at end of file diff --git a/guide/src/templates/commands/gm/hermes_cc b/guide/src/templates/commands/gm/hermes_cc new file mode 100644 index 0000000000..8b425d94ed --- /dev/null +++ b/guide/src/templates/commands/gm/hermes_cc @@ -0,0 +1 @@ +[[#binary gm]] hermes cc \ No newline at end of file diff --git a/guide/src/templates/commands/gm/hermes_cc_exec b/guide/src/templates/commands/gm/hermes_cc_exec new file mode 100644 index 0000000000..d25b564fdc --- /dev/null +++ b/guide/src/templates/commands/gm/hermes_cc_exec @@ -0,0 +1 @@ +[[#binary gm]] hermes cc --exec \ No newline at end of file diff --git a/guide/src/templates/commands/gm/hermes_config b/guide/src/templates/commands/gm/hermes_config new file mode 100644 index 0000000000..54a20fe980 --- /dev/null +++ b/guide/src/templates/commands/gm/hermes_config @@ -0,0 +1 @@ +[[#binary gm]] hermes config \ No newline at end of file diff --git a/guide/src/templates/commands/gm/hermes_keys b/guide/src/templates/commands/gm/hermes_keys new file mode 100644 index 0000000000..8fd662c614 --- /dev/null +++ b/guide/src/templates/commands/gm/hermes_keys @@ -0,0 +1 @@ +[[#binary gm]] hermes keys \ No newline at end of file diff --git a/guide/src/templates/commands/gm/keys b/guide/src/templates/commands/gm/keys new file mode 100644 index 0000000000..ca79ca012d --- /dev/null +++ b/guide/src/templates/commands/gm/keys @@ -0,0 +1 @@ +[[#binary gm]] keys \ No newline at end of file diff --git a/guide/src/templates/commands/gm/reset b/guide/src/templates/commands/gm/reset new file mode 100644 index 0000000000..9c6261d283 --- /dev/null +++ b/guide/src/templates/commands/gm/reset @@ -0,0 +1 @@ +[[#binary gm]] reset \ No newline at end of file diff --git a/guide/src/templates/commands/gm/rm b/guide/src/templates/commands/gm/rm new file mode 100644 index 0000000000..c1e60978af --- /dev/null +++ b/guide/src/templates/commands/gm/rm @@ -0,0 +1 @@ +[[#binary gm]] rm [[#folder]] \ No newline at end of file diff --git a/guide/src/templates/commands/gm/start b/guide/src/templates/commands/gm/start new file mode 100644 index 0000000000..5a67e8a2a0 --- /dev/null +++ b/guide/src/templates/commands/gm/start @@ -0,0 +1 @@ +[[#binary gm]] start \ No newline at end of file diff --git a/guide/src/templates/commands/gm/status b/guide/src/templates/commands/gm/status new file mode 100644 index 0000000000..0036d5bbe2 --- /dev/null +++ b/guide/src/templates/commands/gm/status @@ -0,0 +1 @@ +[[#binary gm]] status \ No newline at end of file diff --git a/guide/src/templates/commands/gm/stop b/guide/src/templates/commands/gm/stop new file mode 100644 index 0000000000..a518daf996 --- /dev/null +++ b/guide/src/templates/commands/gm/stop @@ -0,0 +1 @@ +[[#binary gm]] stop \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/clear_packets b/guide/src/templates/commands/hermes/clear_packets new file mode 100644 index 0000000000..8465958d14 --- /dev/null +++ b/guide/src/templates/commands/hermes/clear_packets @@ -0,0 +1 @@ +[[#binary hermes]] clear packets --chain [[#chain]] --port [[#port]] --channel [[#channel]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/completions b/guide/src/templates/commands/hermes/completions new file mode 100644 index 0000000000..d6d36cfda8 --- /dev/null +++ b/guide/src/templates/commands/hermes/completions @@ -0,0 +1 @@ +[[#binary hermes]] completions --shell [[#shell]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/config_auto b/guide/src/templates/commands/hermes/config_auto new file mode 100644 index 0000000000..346b735f3b --- /dev/null +++ b/guide/src/templates/commands/hermes/config_auto @@ -0,0 +1 @@ +[[#binary hermes]] config auto --output [[#output]] --chains [[#chains]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/config_validate b/guide/src/templates/commands/hermes/config_validate new file mode 100644 index 0000000000..e3f455ef7a --- /dev/null +++ b/guide/src/templates/commands/hermes/config_validate @@ -0,0 +1 @@ +[[#binary hermes]] config validate \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/create_channel b/guide/src/templates/commands/hermes/create_channel new file mode 100644 index 0000000000..aa770ea258 --- /dev/null +++ b/guide/src/templates/commands/hermes/create_channel @@ -0,0 +1 @@ +[[#binary hermes]] create channel --a-chain [[#a-chain]] --a-connection [[#a-connection]] --a-port [[#a-port]] --b-port [[#b-port]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/create_channel_new_client b/guide/src/templates/commands/hermes/create_channel_new_client new file mode 100644 index 0000000000..66cb37518a --- /dev/null +++ b/guide/src/templates/commands/hermes/create_channel_new_client @@ -0,0 +1 @@ +[[#binary hermes]] create channel --a-chain [[#a-chain]] --b-chain [[#b-chain]] --a-port [[#a-port]] --b-port [[#b-port]] --new-client-connection --yes \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/create_client b/guide/src/templates/commands/hermes/create_client new file mode 100644 index 0000000000..3a9653c305 --- /dev/null +++ b/guide/src/templates/commands/hermes/create_client @@ -0,0 +1 @@ +[[#binary hermes]] create client --host-chain [[#host-chain]] --reference-chain [[#reference-chain]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/create_connection b/guide/src/templates/commands/hermes/create_connection new file mode 100644 index 0000000000..31df179f50 --- /dev/null +++ b/guide/src/templates/commands/hermes/create_connection @@ -0,0 +1 @@ +[[#binary hermes]] create connection --a-chain [[#a-chain]] --a-client [[#a-client]] --b-client [[#b-client]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/health_check b/guide/src/templates/commands/hermes/health_check new file mode 100644 index 0000000000..49a2533f4f --- /dev/null +++ b/guide/src/templates/commands/hermes/health_check @@ -0,0 +1 @@ +[[#binary hermes]] health-check \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/keys_add_key_file b/guide/src/templates/commands/hermes/keys_add_key_file new file mode 100644 index 0000000000..c79779ad49 --- /dev/null +++ b/guide/src/templates/commands/hermes/keys_add_key_file @@ -0,0 +1 @@ +[[#binary hermes]] keys add --chain [[#chain]] --key-file [[#key-file]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/keys_add_mnemonic b/guide/src/templates/commands/hermes/keys_add_mnemonic new file mode 100644 index 0000000000..25b7ea8f32 --- /dev/null +++ b/guide/src/templates/commands/hermes/keys_add_mnemonic @@ -0,0 +1 @@ +[[#binary hermes]] keys add --chain [[#chain]] --mnemonic-file [[#mnemonic-file]] --key-name [[#key-name]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/optional_config_flag/clear_packets b/guide/src/templates/commands/hermes/optional_config_flag/clear_packets new file mode 100644 index 0000000000..921482a09b --- /dev/null +++ b/guide/src/templates/commands/hermes/optional_config_flag/clear_packets @@ -0,0 +1 @@ +[[#binary hermes]] --config [[#config]] clear packets --chain [[#chain]] --port [[#port]] --channel [[#channel]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/optional_config_flag/start b/guide/src/templates/commands/hermes/optional_config_flag/start new file mode 100644 index 0000000000..e3bd5d05df --- /dev/null +++ b/guide/src/templates/commands/hermes/optional_config_flag/start @@ -0,0 +1 @@ +[[#binary hermes]] --config [[#config]] start \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/query_channels_show_counterparty b/guide/src/templates/commands/hermes/query_channels_show_counterparty new file mode 100644 index 0000000000..34a9d41ea2 --- /dev/null +++ b/guide/src/templates/commands/hermes/query_channels_show_counterparty @@ -0,0 +1 @@ +[[#binary hermes]] query channels --chain [[#chain]] --show-counterparty \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/query_packet_pending b/guide/src/templates/commands/hermes/query_packet_pending new file mode 100644 index 0000000000..9527bde38d --- /dev/null +++ b/guide/src/templates/commands/hermes/query_packet_pending @@ -0,0 +1 @@ +[[#binary hermes]] query packet pending --chain [[#chain]] --port [[#port]] --channel [[#channel]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/start b/guide/src/templates/commands/hermes/start new file mode 100644 index 0000000000..04aba83333 --- /dev/null +++ b/guide/src/templates/commands/hermes/start @@ -0,0 +1 @@ +[[#binary hermes]] start \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/transfer b/guide/src/templates/commands/hermes/transfer new file mode 100644 index 0000000000..f669fae5e4 --- /dev/null +++ b/guide/src/templates/commands/hermes/transfer @@ -0,0 +1 @@ +[[#binary hermes]] tx ft-transfer --dst-chain [[#dst-chain]] --src-chain [[#src-chain]] --src-port [[#src-port]] --src-channel [[#src-channel]] --amount [[#amount]] --timeout-seconds [[#timeout-seconds]] [[#other]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/transfer_with_denom b/guide/src/templates/commands/hermes/transfer_with_denom new file mode 100644 index 0000000000..111cd6651d --- /dev/null +++ b/guide/src/templates/commands/hermes/transfer_with_denom @@ -0,0 +1 @@ +[[#binary hermes]] tx ft-transfer --dst-chain [[#dst-chain]] --src-chain [[#src-chain]] --src-port [[#src-port]] --src-channel [[#src-channel]] --amount [[#amount]] --timeout-seconds [[#timeout-seconds]] --denom [[#denom]] \ No newline at end of file diff --git a/guide/src/templates/commands/hermes/version b/guide/src/templates/commands/hermes/version new file mode 100644 index 0000000000..98ef9ef1cb --- /dev/null +++ b/guide/src/templates/commands/hermes/version @@ -0,0 +1 @@ +[[#binary hermes]] version \ No newline at end of file diff --git a/guide/src/templates/files/gm/default_gm.toml b/guide/src/templates/files/gm/default_gm.toml new file mode 100644 index 0000000000..b23c6d55ac --- /dev/null +++ b/guide/src/templates/files/gm/default_gm.toml @@ -0,0 +1,34 @@ +[global] + add_to_hermes = false + auto_maintain_config = true + extra_wallets = 2 + gaiad_binary = "~/go/bin/gaiad" + hdpath = "" + home_dir = "$HOME/.gm" + ports_start_at = 27000 + validator_mnemonic = "" + wallet_mnemonic = "" + + [global.hermes] + binary = "./hermes" #change this path according to your setup + config = "$HOME/.hermes/config.toml" + log_level = "info" + telemetry_enabled = true + telemetry_host = "127.0.0.1" + telemetry_port = 3001 + +[ibc-0] + ports_start_at = 27010 + +[ibc-1] + ports_start_at = 27020 + +[node-0] + add_to_hermes = true + network = "ibc-0" + ports_start_at = 27030 + +[node-1] + add_to_hermes = true + network = "ibc-1" + ports_start_at = 27040 \ No newline at end of file diff --git a/guide/src/templates/files/gm/more-chains/gm.toml b/guide/src/templates/files/gm/more-chains/gm.toml new file mode 100644 index 0000000000..b88ad7e86d --- /dev/null +++ b/guide/src/templates/files/gm/more-chains/gm.toml @@ -0,0 +1,50 @@ +[global] + add_to_hermes = false + auto_maintain_config = true + extra_wallets = 2 + gaiad_binary = "~/go/bin/gaiad" + hdpath = "" + home_dir = "~/.gm" + ports_start_at = 27000 + validator_mnemonic = "" + wallet_mnemonic = "" + + [global.hermes] + binary = "$HOME/ibc-rs/target/release/hermes" #change this path according to your setup + config = "~/.hermes/config.toml" + log_level = "info" + telemetry_enabled = true + telemetry_host = "127.0.0.1" + telemetry_port = 3001 + +[ibc-0] + ports_start_at = 27010 + +[ibc-1] + ports_start_at = 27020 + +[ibc-2] + ports_start_at = 27030 + +[ibc-3] + ports_start_at = 27040 + +[node-0] + add_to_hermes = true + network = "ibc-0" + ports_start_at = 27050 + +[node-1] + add_to_hermes = true + network = "ibc-1" + ports_start_at = 27060 + +[node-2] + add_to_hermes = true + network = "ibc-2" + ports_start_at = 27070 + +[node-3] + add_to_hermes = true + network = "ibc-3" + ports_start_at = 27080 \ No newline at end of file diff --git a/guide/src/templates/files/hermes/local-chains/config.toml b/guide/src/templates/files/hermes/local-chains/config.toml new file mode 100644 index 0000000000..57f8b2f5df --- /dev/null +++ b/guide/src/templates/files/hermes/local-chains/config.toml @@ -0,0 +1,56 @@ +[global] +log_level = 'info' + +[mode] + +[mode.clients] +enabled = true +refresh = true +misbehaviour = true + +[mode.connections] +enabled = true + +[mode.channels] +enabled = true + +[mode.packets] +enabled = true +clear_interval = 100 +clear_on_start = true +tx_confirmation = true + +[telemetry] +enabled = true +host = '127.0.0.1' +port = 3001 + +[[chains]] +id = 'ibc-0' +rpc_addr = 'http://localhost:27030' +grpc_addr = 'http://localhost:27032' +websocket_addr = 'ws://localhost:27030/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[[chains]] +id = 'ibc-1' +rpc_addr = 'http://localhost:27040' +grpc_addr = 'http://localhost:27042' +websocket_addr = 'ws://localhost:27040/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } \ No newline at end of file diff --git a/guide/src/templates/files/hermes/more-chains/config_with_filters.toml b/guide/src/templates/files/hermes/more-chains/config_with_filters.toml new file mode 100644 index 0000000000..a1adc2f134 --- /dev/null +++ b/guide/src/templates/files/hermes/more-chains/config_with_filters.toml @@ -0,0 +1,115 @@ +[global] +log_level = 'info' + +[mode] + +[mode.clients] +enabled = true +refresh = true +misbehaviour = true + +[mode.connections] +enabled = true + +[mode.channels] +enabled = true + +[mode.packets] +enabled = true +clear_interval = 100 +clear_on_start = true +tx_confirmation = true + +[telemetry] +enabled = true +host = '127.0.0.1' +port = 3001 + +[[chains]] +id = 'ibc-0' +rpc_addr = 'http://localhost:27050' +grpc_addr = 'http://localhost:27052' +websocket_addr = 'ws://localhost:27050/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-2'], +] + +[[chains]] +id = 'ibc-1' +rpc_addr = 'http://localhost:27060' +grpc_addr = 'http://localhost:27062' +websocket_addr = 'ws://localhost:27060/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-1'], +] + +[[chains]] +id = 'ibc-2' +rpc_addr = 'http://localhost:27070' +grpc_addr = 'http://localhost:27072' +websocket_addr = 'ws://localhost:27070/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-1'], + ['transfer', 'channel-2'], +] + +[[chains]] +id = 'ibc-3' +rpc_addr = 'http://localhost:27080' +grpc_addr = 'http://localhost:27082' +websocket_addr = 'ws://localhost:27080/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-2'], +] \ No newline at end of file diff --git a/guide/src/templates/files/hermes/more-chains/config_without_filters.toml b/guide/src/templates/files/hermes/more-chains/config_without_filters.toml new file mode 100644 index 0000000000..11a74570de --- /dev/null +++ b/guide/src/templates/files/hermes/more-chains/config_without_filters.toml @@ -0,0 +1,86 @@ +[global] +log_level = 'info' + +[mode] + +[mode.clients] +enabled = true +refresh = true +misbehaviour = true + +[mode.connections] +enabled = true + +[mode.channels] +enabled = true + +[mode.packets] +enabled = true +clear_interval = 100 +clear_on_start = true +tx_confirmation = true + +[telemetry] +enabled = true +host = '127.0.0.1' +port = 3001 + +[[chains]] +id = 'ibc-0' +rpc_addr = 'http://localhost:27050' +grpc_addr = 'http://localhost:27052' +websocket_addr = 'ws://localhost:27050/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[[chains]] +id = 'ibc-1' +rpc_addr = 'http://localhost:27060' +grpc_addr = 'http://localhost:27062' +websocket_addr = 'ws://localhost:27060/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[[chains]] +id = 'ibc-2' +rpc_addr = 'http://localhost:27070' +grpc_addr = 'http://localhost:27072' +websocket_addr = 'ws://localhost:27070/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[[chains]] +id = 'ibc-3' +rpc_addr = 'http://localhost:27080' +grpc_addr = 'http://localhost:27082' +websocket_addr = 'ws://localhost:27080/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } \ No newline at end of file diff --git a/guide/src/templates/files/hermes/more-chains/hermes_second_instance.toml b/guide/src/templates/files/hermes/more-chains/hermes_second_instance.toml new file mode 100644 index 0000000000..be1f559908 --- /dev/null +++ b/guide/src/templates/files/hermes/more-chains/hermes_second_instance.toml @@ -0,0 +1,111 @@ +[global] +log_level = 'info' + +[mode] + +[mode.clients] +enabled = true +refresh = true +misbehaviour = true + +[mode.connections] +enabled = true + +[mode.channels] +enabled = true + +[mode.packets] +enabled = true +clear_interval = 100 +clear_on_start = true +tx_confirmation = true + +[telemetry] +enabled = true +host = '127.0.0.1' +port = 3002 + +[[chains]] +id = 'ibc-0' +rpc_addr = 'http://localhost:27050' +grpc_addr = 'http://localhost:27052' +websocket_addr = 'ws://localhost:27050/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet1' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-1'], +] + +[[chains]] +id = 'ibc-1' +rpc_addr = 'http://localhost:27060' +grpc_addr = 'http://localhost:27062' +websocket_addr = 'ws://localhost:27060/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet1' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-2'], +] + +[[chains]] +id = 'ibc-2' +rpc_addr = 'http://localhost:27070' +grpc_addr = 'http://localhost:27072' +websocket_addr = 'ws://localhost:27070/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet1' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-0'], +] + +[[chains]] +id = 'ibc-3' +rpc_addr = 'http://localhost:27080' +grpc_addr = 'http://localhost:27082' +websocket_addr = 'ws://localhost:27080/websocket' +rpc_timeout = '15s' +account_prefix = 'cosmos' +key_name = 'wallet1' +store_prefix = 'ibc' +gas_price = { price = 0.01, denom = 'stake' } +max_gas = 10000000 +clock_drift = '5s' +trusting_period = '14days' +trust_threshold = { numerator = '1', denominator = '3' } + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', 'channel-1'], +] \ No newline at end of file diff --git a/guide/src/templates/files/hermes/production/config.toml b/guide/src/templates/files/hermes/production/config.toml new file mode 100644 index 0000000000..88ac93bf2c --- /dev/null +++ b/guide/src/templates/files/hermes/production/config.toml @@ -0,0 +1,106 @@ +[global] +log_level = 'info' +[mode.clients] +enabled = true +refresh = true +misbehaviour = false + +[mode.connections] +enabled = false + +[mode.channels] +enabled = false + +[mode.packets] +enabled = true +clear_interval = 100 +clear_on_start = true +tx_confirmation = false + +[rest] +enabled = false +host = '127.0.0.1' +port = 3000 + +[telemetry] +enabled = false +host = '127.0.0.1' +port = 3001 + +[[chains]] +id = 'cosmoshub-4' +type = 'CosmosSdk' +rpc_addr = 'https://rpc.cosmoshub.strange.love/' +websocket_addr = 'wss://rpc.cosmoshub.strange.love/websocket' +grpc_addr = 'https://grpc-cosmoshub-ia.notional.ventures/' +rpc_timeout = '10s' +account_prefix = 'cosmos' +key_name = 'keyhub' +key_store_type = 'Test' +store_prefix = 'ibc' +default_gas = 100000 +max_gas = 400000 +gas_multiplier = 1.1 +max_msg_num = 30 +max_tx_size = 2097152 +clock_drift = '5s' +max_block_time = '30s' +memo_prefix = '' +sequential_batch_tx = false + +[chains.trust_threshold] +numerator = '1' +denominator = '3' + +[chains.gas_price] +price = 0.1 +denom = 'uatom' + +[chains.packet_filter] +policy = 'allow' +list = [[ + 'transfer', + 'channel-141', +]] + +[chains.address_type] +derivation = 'cosmos' + +[[chains]] +id = 'osmosis-1' +type = 'CosmosSdk' +rpc_addr = 'https://rpc.osmosis.interbloc.org/' +websocket_addr = 'wss://rpc.osmosis.interbloc.org/websocket' +grpc_addr = 'https://grpc-osmosis-ia.notional.ventures/' +rpc_timeout = '10s' +account_prefix = 'osmo' +key_name = 'keyosmosis' +key_store_type = 'Test' +store_prefix = 'ibc' +default_gas = 100000 +max_gas = 400000 +gas_multiplier = 1.1 +max_msg_num = 30 +max_tx_size = 2097152 +clock_drift = '5s' +max_block_time = '30s' +memo_prefix = '' +sequential_batch_tx = false + +[chains.trust_threshold] +numerator = '1' +denominator = '3' + +[chains.gas_price] +price = 0.1 +denom = 'uosmo' + +[chains.packet_filter] +policy = 'allow' +list = [[ + 'transfer', + 'channel-0', +]] + +[chains.address_type] +derivation = 'cosmos' \ No newline at end of file diff --git a/guide/src/templates/files/hermes/production/default_gas_cosmoshub b/guide/src/templates/files/hermes/production/default_gas_cosmoshub new file mode 100644 index 0000000000..92d250ae7f --- /dev/null +++ b/guide/src/templates/files/hermes/production/default_gas_cosmoshub @@ -0,0 +1,8 @@ +default_gas = 2000000 +max_gas = 10000000 +gas_multiplier = 1.1 +max_msg_num = 25 +# ... +[chains.gas_price] +price = 0.005 +denom = 'uatom' \ No newline at end of file diff --git a/guide/src/templates/files/hermes/production/default_gas_osmosis b/guide/src/templates/files/hermes/production/default_gas_osmosis new file mode 100644 index 0000000000..a217df797a --- /dev/null +++ b/guide/src/templates/files/hermes/production/default_gas_osmosis @@ -0,0 +1,8 @@ +default_gas = 5000000 +max_gas = 15000000 +gas_multiplier = 1.1 +max_msg_num = 20 +# ... +[chains.gas_price] +price = 0.0026 +denom = 'uosmo' \ No newline at end of file diff --git a/guide/src/templates/path/gm/_template _templates_path_gm_default_path_.code-search b/guide/src/templates/path/gm/_template _templates_path_gm_default_path_.code-search new file mode 100644 index 0000000000..6c75c4fcb7 --- /dev/null +++ b/guide/src/templates/path/gm/_template _templates_path_gm_default_path_.code-search @@ -0,0 +1,34 @@ +# Query: {{#template ../../templates/path/gm/default_path}} +# ContextLines: 1 + +7 résultats - Fichiers 4 + +src/templates/path/default_path: + 1: {{#template ../../templates/path/gm/default_path}} + +src/tutorials/local-chains/start-local-chains.md: + 15 + 16: Make sure you have the `{{#template ../../templates/path/gm/default_path}}` that we configured in the previous section [Install Gaiad Manager](../pre-requisites/gaiad-manager.md). If this is not the first time you are running the script, you can manually stop the two gaia instances executing the following command to kill all `gaiad` processes: + 17 + + 235 > __TROUBLESHOOTING__: + 236: > - If the command does not out output anything, make sure the path to Hermes' binary is set in `{{#template ../../templates/path/gm/default_path}}`. + 237 + +src/tutorials/more-chains/start-local-chains.md: + 37 + 38: Copy and paste the configuration below to `{{#template ../../templates/path/gm/default_path}}` and set Hermes' binary path according to your setup. The following contains the configuration of 4 IBC-enabled chains. + 39 + + 284 > __TROUBLESHOOTING__: + 285: > - If the command does not out output anything, make sure the path to Hermes' binary is set in `{{#template ../../templates/path/gm/default_path}}`. + 286 + +src/tutorials/pre-requisites/gaiad-manager.md: + 69 ### The configuration: `gm.toml` + 70: **Where**: `{{#template ../../templates/path/gm/default_path}}`. + 71 + + 75 + 76: Copy and paste below to `{{#template ../../templates/path/gm/default_path}}` and set Hermes' binary path according to your setup. + 77 diff --git a/guide/src/templates/path/gm/default_path b/guide/src/templates/path/gm/default_path new file mode 100644 index 0000000000..2dca8881e1 --- /dev/null +++ b/guide/src/templates/path/gm/default_path @@ -0,0 +1 @@ +$HOME/.gm/gm.toml \ No newline at end of file diff --git a/guide/src/templates/version b/guide/src/templates/version new file mode 100644 index 0000000000..60453e6906 --- /dev/null +++ b/guide/src/templates/version @@ -0,0 +1 @@ +v1.0.0 \ No newline at end of file diff --git a/guide/src/tutorials/index.md b/guide/src/tutorials/index.md index 6bfa184e2c..c51f90ff78 100644 --- a/guide/src/tutorials/index.md +++ b/guide/src/tutorials/index.md @@ -1,9 +1,15 @@ # Tutorials -This section includes tutorials for some common relayer use cases and commands. You can also refer to the [Commands Reference](../commands/index.md) section to learn more about individual commands. - -## Basic tutorials - -**[Two Local Chains](./local-chains/index.md)** - -In this tutorial you will learn how to start two local [`Cosmos Gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol and start relaying packets between them. +This section includes tutorials to learn the basics of relaying and the main commands. You can also refer to the [Commands Reference](../documentation/commands/index.md) section to learn more about individual commands. + +--- + +## Sections +- **[Prerequisites for local chains](./pre-requisites/index.md)** + * Install `Gaia` and `gm` (Gaia Manager) for tutorials using local chains. +- **[Two Local Chains](./local-chains/index.md)** + * Start two local [`Cosmos Gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol and learn the fundamentals of IBC. +- **[More Local Chains](./more-chains/index.md)** + * Learn how to relay on an arbitrary topology of more than two chains by using packet filters and to run multiple instances of Hermes. +- **[Relaying in production](./production/index.md)** + * Learn how to set up, configure and run `hermes` on IBC-enabled chains in production. diff --git a/guide/src/tutorials/local-chains/add-a-new-relay-path.md b/guide/src/tutorials/local-chains/add-a-new-relay-path.md new file mode 100644 index 0000000000..4f06566043 --- /dev/null +++ b/guide/src/tutorials/local-chains/add-a-new-relay-path.md @@ -0,0 +1,574 @@ +# Add a new relay path + +In order to connect two IBC-enabled chains, both chains need an on-chain client that keeps track of the other chain. These two clients can be connected by one or multiple connections. Then, channels need to be created, over a connection, to specify the destination module. + +> __WARNING__: In production, do not create clients, connections or channels between two chains before checking that a client/connection/channel does not already fulfill the same function. + +--- + +## Identifiers + +A chain allocates identifiers when it creates clients, connections and channels. These identifiers can subsequently be used to refer to existing clients, connections, and channels. + +> NOTE: If you want to ensure you get the same identifiers while following the tutorials, run each of the commands in this page only __once__ or reset the chains as instructed in section [Start local chains](./start-local-chains.md#reset-your-configuration-and-start-the-chains). + +Chains allocate identifiers using a chain-specific allocation scheme. Currently, the *cosmos-sdk* implementation uses the following identifiers: + +- `07-tendermint-` for tendermint clients. +- `connection-` for connections. +- `channel-` for channels. + +It is possible for two chains to use the same identifier to designate two different objects. For example, two different channels, one on the Hub and one on Osmosis, can both be designated with the `channel-0` identifier. + + +## Create the relay path + +A relay path refers to a specific channel used to interconnect two chains and over which packets are being sent. + +Hermes can be started to listen for packet events on the two ends of multiple paths and relay packets over these paths. +This can be done over a new path or over existing paths. + +>__NOTE__: The following steps decompose every step from the creation of the clients to the channel handshake for educational purposes. +> More realistically, you'd use the command `{{#template ../../templates/commands/hermes/create_channel_new_client a-chain=ibc-0 b-chain=ibc-1 a-port=transfer b-port=transfer}}` in order to create a new client on each chain, establish a connection, and open a channel, all with a single command. + +You will need to first create a client on both chains and then establish a connection between them. It is possible to have multiple connections between clients, which can be useful in order to support multiple versions of IBC. Finally, you need to create channels over a connection to identify the source and destination modules. You can learn more in the [cosmos academy tutorial](https://tutorials.cosmos.network/academy/4-ibc/what-is-ibc.html). + +### Create clients + +First, create a client on `ibc-1` tracking the state of `ibc-0`. It will be assigned `07-tendermint-0` as its identifier: + +```shell +{{#template ../../templates/commands/hermes/create_client host-chain=ibc-1 reference-chain=ibc-0}} +``` + +If the command is successful, the output should be similar to: +```json +SUCCESS CreateClient( + CreateClient( + Attributes { + client_id: ClientId( + "07-tendermint-0", + ), + client_type: Tendermint, + consensus_height: Height { + revision: 0, + height: 2, + }, + }, + ), +) +``` + +Now, create a client on `ibc-0` tracking `ibc-1`: + +```shell +{{#template ../../templates/commands/hermes/create_client host-chain=ibc-0 reference-chain=ibc-1}} +``` +If the command is successful, the output should be similar to: +```json +SUCCESS CreateClient( + CreateClient( + Attributes { + client_id: ClientId( + "07-tendermint-0", + ), + client_type: Tendermint, + consensus_height: Height { + revision: 1, + height: 3, + }, + }, + ), +) +``` +As you can see, the identifier is also `07-tendermint-0` because the client-id is **local to a chain**. + + +### 2. Create connections + + +After creating clients on both chains, you have to establish a connection between them. Both chains will assign `connection-0` as the identifier of their first connection: + +```shell +{{#template ../../templates/commands/hermes/create_connection a-chain=ibc-0 a-client=07-tendermint-0 b-client=07-tendermint-0}} +``` +>__NOTE__: The command does not take `--b-chain` as argument as `--a-client` can only track one chain (`ibc-1`). + +If the command runs successfully, it should output something similar to: + +
Create connection output + +``` +2022-08-29T11:16:39.833467Z INFO ThreadId(01) using default configuration from '$HOME/.hermes/config.toml' +2022-08-29T11:16:39.838071Z INFO ThreadId(01) Creating a new connection with pre-existing clients 07-tendermint-0 and 07-tendermint-0 +2022-08-29T11:16:39.843103Z INFO ThreadId(15) wait_for_block_commits: waiting for commit of tx hashes(s) F87AE29F8BA86EA9F6533C0CE8A34101C90948B824446E0B4889C4F953A9E094 id=ibc-0 +2022-08-29T11:16:41.047867Z INFO ThreadId(01) 🥂 ibc-0 => IbcEventWithHeight { + event: OpenInitConnection( + OpenInit( + Attributes { + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + client_id: ClientId( + "07-tendermint-0", + ), + counterparty_connection_id: None, + counterparty_client_id: ClientId( + "07-tendermint-0", + ), + }, + ), + ), + height: Height { + revision: 0, + height: 29, + }, +} + +2022-08-29T11:16:44.061620Z INFO ThreadId(15) wait_for_block_commits: waiting for commit of tx hashes(s) AEEAE5846991C6748248ECD81A5B8D83E7E0388322202900788C72518649EF7B id=ibc-0 +2022-08-29T11:16:51.249114Z INFO ThreadId(41) wait_for_block_commits: waiting for commit of tx hashes(s) BFED59B2EBE5D75A19C1CBB1FB931FF6FC81EF02F872CEB3D37AA40DDA5101B4 id=ibc-1 +2022-08-29T11:16:52.452619Z INFO ThreadId(01) 🥂 ibc-1 => IbcEventWithHeight { + event: OpenTryConnection( + OpenTry( + Attributes { + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + client_id: ClientId( + "07-tendermint-0", + ), + counterparty_connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + counterparty_client_id: ClientId( + "07-tendermint-0", + ), + }, + ), + ), + height: Height { + revision: 1, + height: 31, + }, +} + +2022-08-29T11:16:55.459367Z WARN ThreadId(01) [ibc-0 -> ibc-1:07-tendermint-0] resolving trusted height from the full list of consensus state heights for target height 0-31; this may take a while +2022-08-29T11:16:55.469498Z INFO ThreadId(41) wait_for_block_commits: waiting for commit of tx hashes(s) D232FCF03549B692604A06AFC1D82494FB1D466E61880E9A8653FEFC2F41BA69 id=ibc-1 +2022-08-29T11:17:02.248045Z INFO ThreadId(15) wait_for_block_commits: waiting for commit of tx hashes(s) 0ABC352714048C0873537CCEBE31393E1CB09F810B5AAE495833436A8F9447C0 id=ibc-0 +2022-08-29T11:17:06.159408Z INFO ThreadId(01) 🥂 ibc-0 => IbcEventWithHeight { + event: OpenAckConnection( + OpenAck( + Attributes { + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + client_id: ClientId( + "07-tendermint-0", + ), + counterparty_connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + counterparty_client_id: ClientId( + "07-tendermint-0", + ), + }, + ), + ), + height: Height { + revision: 0, + height: 34, + }, +} + +2022-08-29T11:17:11.202362Z INFO ThreadId(41) wait_for_block_commits: waiting for commit of tx hashes(s) F5A344056C7F8775620581756985C2C5DB43F396A18956C017E56EFB4A8FF616 id=ibc-1 +2022-08-29T11:17:12.407373Z INFO ThreadId(01) 🥂 ibc-1 => IbcEventWithHeight { + event: OpenConfirmConnection( + OpenConfirm( + Attributes { + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + client_id: ClientId( + "07-tendermint-0", + ), + counterparty_connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + counterparty_client_id: ClientId( + "07-tendermint-0", + ), + }, + ), + ), + height: Height { + revision: 1, + height: 35, + }, +} + +2022-08-29T11:17:15.409868Z INFO ThreadId(01) connection handshake already finished for Connection { + delay_period: 0ns, + a_side: ConnectionSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-0", + version: 0, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + }, + b_side: ConnectionSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-1", + version: 1, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + }, +} + +SUCCESS Connection { + delay_period: 0ns, + a_side: ConnectionSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-0", + version: 0, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + }, + b_side: ConnectionSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-1", + version: 1, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: Some( + ConnectionId( + "connection-0", + ), + ), + }, +} +``` +
+ +### 3. Channel identifiers + + +Finally, after the connection has been established, you can now open a new channel on top of it. Both chains will assign `channel-0` as the identifier of their first channel: + +```shell +{{#template ../../templates/commands/hermes/create_channel a-chain=ibc-0 a-connection=connection-0 a-port=transfer b-port=transfer}} +``` +>__NOTE__: Again, you do not need to specify the counterparty chain as a connection can only be established with a single counterparty. The `port` specifies the protocol which will be used on this channel. + +If the command runs succesfully, it should output something similar to: + +
Create channel output + +``` +2022-08-29T11:26:28.027659Z INFO ThreadId(01) using default configuration from '$HOME/.hermes/config.toml' +2022-08-29T11:26:28.040558Z INFO ThreadId(15) wait_for_block_commits: waiting for commit of tx hashes(s) A7B19D0BB98DD6724B7E41A2CAD8381989D38C8D9E8C141D111DBF9DB5C20DC1 id=ibc-0 +2022-08-29T11:26:33.455062Z INFO ThreadId(01) 🎊 ibc-0 => IbcEventWithHeight { + event: OpenInitChannel( + OpenInit { + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + connection_id: ConnectionId( + "connection-0", + ), + counterparty_port_id: PortId( + "transfer", + ), + counterparty_channel_id: None, + }, + ), + height: Height { + revision: 0, + height: 147, + }, +} + +2022-08-29T11:26:38.199410Z INFO ThreadId(41) wait_for_block_commits: waiting for commit of tx hashes(s) 31CBCFAA6806315A5A6D96C71AEBFDFD71757F823914037B51893F123332282D id=ibc-1 +2022-08-29T11:26:39.704788Z INFO ThreadId(01) 🎊 ibc-1 => IbcEventWithHeight { + event: OpenTryChannel( + OpenTry { + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + connection_id: ConnectionId( + "connection-0", + ), + counterparty_port_id: PortId( + "transfer", + ), + counterparty_channel_id: Some( + ChannelId( + "channel-0", + ), + ), + }, + ), + height: Height { + revision: 1, + height: 148, + }, +} + +2022-08-29T11:26:44.242127Z INFO ThreadId(15) wait_for_block_commits: waiting for commit of tx hashes(s) 0B6EAF8ABCC7E807EDBD65E73EEE32CEE736BE787D2791C49D1436F2BA810F37 id=ibc-0 +2022-08-29T11:26:48.455749Z INFO ThreadId(01) 🎊 ibc-0 => IbcEventWithHeight { + event: OpenAckChannel( + OpenAck { + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + counterparty_channel_id: Some( + ChannelId( + "channel-0", + ), + ), + connection_id: ConnectionId( + "connection-0", + ), + counterparty_port_id: PortId( + "transfer", + ), + }, + ), + height: Height { + revision: 0, + height: 150, + }, +} + +2022-08-29T11:26:53.297494Z INFO ThreadId(41) wait_for_block_commits: waiting for commit of tx hashes(s) 005B0105B4E1541F3ABF56CF5AB340EDA4DE0A81939CF379F1FEA272160C47EE id=ibc-1 +2022-08-29T11:26:54.501966Z INFO ThreadId(01) 🎊 ibc-1 => IbcEventWithHeight { + event: OpenConfirmChannel( + OpenConfirm { + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + connection_id: ConnectionId( + "connection-0", + ), + counterparty_port_id: PortId( + "transfer", + ), + counterparty_channel_id: Some( + ChannelId( + "channel-0", + ), + ), + }, + ), + height: Height { + revision: 1, + height: 151, + }, +} + +2022-08-29T11:26:57.503582Z INFO ThreadId(01) channel handshake already finished for Channel { + ordering: Unordered, + a_side: ChannelSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-0", + version: 0, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: ConnectionId( + "connection-0", + ), + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + version: None, + }, + b_side: ChannelSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-1", + version: 1, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: ConnectionId( + "connection-0", + ), + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + version: None, + }, + connection_delay: 0ns, +} + +SUCCESS Channel { + ordering: Unordered, + a_side: ChannelSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-0", + version: 0, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: ConnectionId( + "connection-0", + ), + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + version: None, + }, + b_side: ChannelSide { + chain: BaseChainHandle { + chain_id: ChainId { + id: "ibc-1", + version: 1, + }, + runtime_sender: Sender { .. }, + }, + client_id: ClientId( + "07-tendermint-0", + ), + connection_id: ConnectionId( + "connection-0", + ), + port_id: PortId( + "transfer", + ), + channel_id: Some( + ChannelId( + "channel-0", + ), + ), + version: None, + }, + connection_delay: 0ns, +} +``` +
+ +## Visualize the current network + +You can visualize the topology of the current network with: + +```shell +{{#template ../../templates/commands/hermes/query_channels_show_counterparty chain=ibc-0}} +``` + +If all the commands were successful, this command should output : + +``` +ibc-0: transfer/channel-0 --- ibc-1: transfer/channel-0 +``` + +The chains __ibc-0__ and __ibc-1__ are now set up and configured as so: + +__Relay path__: +```mermaid +flowchart LR + A((ibc-0))---B(transfer
channel-0)---C(transfer
channel-0)---D((ibc-1)) +``` + +Before going over the next sections, please ensure the commands above are executed. + +--- + +## Next Steps + +The [following section](./start-relaying.md) describes how to relay packets over the relay path you just created. + diff --git a/guide/src/tutorials/local-chains/gaia.md b/guide/src/tutorials/local-chains/gaia.md deleted file mode 100644 index dda8e58fd4..0000000000 --- a/guide/src/tutorials/local-chains/gaia.md +++ /dev/null @@ -1,46 +0,0 @@ -# Install Gaia - -For `gm` to start the chains, it requires gaia to be installed. - -> __NOTE__: This assumes you have `Golang` programming language installed on -> your machine. If not, please ensure you install before proceeding. See -> more details in the [Pre-requisites](../../pre_requisites.md#2-golang) section. - -#### Clone gaia - -Clone the repository from Github: - -```shell -git clone https://github.com/cosmos/gaia.git ~/go/src/github.com/cosmos/gaia -``` - -#### Build and Install - -Run the `make` command to build and install `gaiad` - -```shell -cd ~/go/src/github.com/cosmos/gaia -git checkout -make install -``` -> Find the [latest-release-tag](https://github.com/cosmos/gaia/releases) here. - ->__NOTE__: Specific to M1 MacOS, there could be some warnings after running `make install` which can be safely ignored as long as `gaiad` binaries are built in `$HOME/go/bin` directory. ->

Add the path `export PATH=$HOME/go/bin:$PATH` - -If the command above is successful you can run the following command to ensure it was properly installed: - -```shell -gaiad version --log_level error --long | head -n4 -``` -Output: -```shell -name: gaia -server_name: gaiad -version: v4.2.1 -commit: dbd8a6fb522c571debf958837f9113c56d418f6b -``` - -## Next Steps - -In the next section you will learn how to [start two local chains](./start.md) diff --git a/guide/src/tutorials/local-chains/gaiad-manager.md b/guide/src/tutorials/local-chains/gaiad-manager.md deleted file mode 100644 index e6b15c93ed..0000000000 --- a/guide/src/tutorials/local-chains/gaiad-manager.md +++ /dev/null @@ -1,113 +0,0 @@ -## Install Gaiad Manager - -Gaiad manager (`gm`) is a command-line tool (CLI) that helps manage local `gaiad` networks. - -Follow the instructions - -### Requirements -* Bourne shell (`sh`) -* [`sconfig`](https://github.com/freshautomations/sconfig/releases) and - [`stoml`](https://github.com/freshautomations/stoml/releases) installed in your PATH (put them in `/usr/local/bin`) -* `sed`, `tr` -* For shell-completion Bourne Again Shell (`bash`) for the local user - -### How to run - -1. Install the dependencies. - -On MacOS: -```bash -# You might need sudo permissions and create the `usr/local/bin` directory - -curl -Lo /usr/local/bin/sconfig https://github.com/freshautomations/sconfig/releases/download/v0.1.0/sconfig_darwin_amd64 -curl -Lo /usr/local/bin/stoml https://github.com/freshautomations/stoml/releases/download/v0.7.0/stoml_darwin_amd64 -chmod 755 /usr/local/bin/sconfig -chmod 755 /usr/local/bin/stoml -``` -On Linux: -```bash -curl -Lo /usr/local/bin/sconfig https://github.com/freshautomations/sconfig/releases/download/v0.1.0/sconfig_linux_amd64 -curl -Lo /usr/local/bin/stoml https://github.com/freshautomations/stoml/releases/download/v0.7.0/stoml_linux_amd64 -chmod 755 /usr/local/bin/sconfig -chmod 755 /usr/local/bin/stoml -``` - -2. Install `gm` - -```bash -git clone https://github.com/informal/ibc-rs -ibc-rs/scripts/gm/bin/gm install -``` -Alternatively, you can create the folder `$HOME/.gm/bin` and copy the files from `scripts/gm/bin` in there. - -3. Activate `gm` -* Add `source $HOME/.gm/bin/shell-support` to a file that executes when a new terminal window comes up - (`$HOME/.bash_profile` or `$HOME/.bashrc` or `$HOME/.zprofile`) -* (Optional) Enable auto-completion -On MacOS: -```bash -# Note: zsh is the default shell on MacOS, so no need to run this unless you explicitly use bash -brew install bash-completion -``` - -On Linux: -``` -apt install bash-completion || yum install bash-completion -``` -* Restart your terminal - -Note: The `shell-support` script allows bash-completion as well as creating a `gm` alias, so you don't need to add more -entries to your PATH environment variable. If you don't want to use this, you can always just add `$HOME/.gm/bin` to -your path. - -### The configuration: `gm.toml` -**Where**: `$HOME/.gm/gm.toml`. - -**Description**: This file contains all the high-level node configuration that `gm` is aware of. Note that all entries under `[global]` are also valid entries under any `[node]` header, and can be used to override the global entries for specific nodes/validators. - -**Entries**: All entries are defined and documented in the `scripts/gm/gm.toml` example configuration file. - -Copy and paste below to `$HOME/.gm/gm.toml` - -The following configuration you need to specify 2 `gaiad` chains. `hermes` will know about these chains. - -```toml -[global] - add_to_hermes = false - auto_maintain_config = true - extra_wallets = 2 - gaiad_binary = "~/go/bin/gaiad" - hdpath = "" - home_dir = "$HOME/.gm" - ports_start_at = 27000 - validator_mnemonic = "" - wallet_mnemonic = "" - - [global.hermes] - binary = "./hermes" #change this path according to your setup - config = "$HOME/.hermes/config.toml" - log_level = "info" - telemetry_enabled = true - telemetry_host = "127.0.0.1" - telemetry_port = 3001 - -[ibc-0] - ports_start_at = 27010 - -[ibc-1] - ports_start_at = 27020 - -[node-0] - add_to_hermes = true - network = "ibc-0" - ports_start_at = 27030 - -[node-1] - add_to_hermes = true - network = "ibc-1" - ports_start_at = 27040 - -``` -In the [next section](start.md) we will configure hermes and start local chains using `gm` - -> __NOTE:__ Go to this page for more detils about [Gaiad Manager](https://github.com/informalsystems/ibc-rs/tree/master/scripts/gm) diff --git a/guide/src/tutorials/local-chains/identifiers.md b/guide/src/tutorials/local-chains/identifiers.md deleted file mode 100644 index e8d04cbb02..0000000000 --- a/guide/src/tutorials/local-chains/identifiers.md +++ /dev/null @@ -1,127 +0,0 @@ -# Identifiers - - -A chain allocates identifiers when it creates clients, connections and channels. These identifiers can subsequently be used to refer to existing clients, connections and channels. - -> NOTE: If you want to ensure you get the same identifiers while following the tutorials, run the each of the three commands below __once__ on `ibc-1`. This will ensure that when going through the tutorial, a second channel on `ibc-1` with identifier `channel-1` will created. - -Chains allocate identifiers using a chain specific allocation scheme. Currently, *cosmos-sdk* implementation uses the follow identifiers: - -### 1. Client Identifiers - -__`07-tendermint-`__ for tendermint clients - -For example `07-tendermint-0` is assigned to the first client created on `ibc-1`: - - ```shell -hermes create client --host-chain ibc-1 --reference-chain ibc-0 - ``` - - ```json -Success: CreateClient( - CreateClient( - Attributes { - height: Height { - revision: 1, - height: 103, - }, - client_id: ClientId( - "07-tendermint-0", - ), - client_type: Tendermint, - consensus_height: Height { - revision: 0, - height: 112, - }, - }, - ), -) - ``` - -We will create a second client on `ibc-1` with identifier `07-tendermint-1` in the client tutorial. - -### 2. Connection Identifiers - -__`connection-`__ for connections - -For example `connection-0` is assigned to the first connection created on `ibc-1`: - -```shell -hermes tx conn-init --dst-chain ibc-1 --src-chain ibc-0 --dst-client 07-tendermint-0 --src-client dummyclientname -``` - -```json -Success: OpenInitConnection( - OpenInit( - Attributes { - height: Height { - revision: 1, - height: 119, - }, - connection_id: Some( - ConnectionId( - "connection-0", - ), - ), - client_id: ClientId( - "07-tendermint-0", - ), - counterparty_connection_id: None, - counterparty_client_id: ClientId( - "dummyclientname", - ), - }, - ), -) -``` -We will create a second connection on `ibc-1` with identifier `connection-1` in the connection tutorial. - -### 3. Channel Identifiers - -`channel-` for channels - -For example `channel-0` is assigned to the first channel created on `ibc-1`: - -```shell -hermes tx chan-open-init --dst-chain ibc-1 --src-chain ibc-0 --dst-connection connection-0 --dst-port transfer --src-port transfer -``` - -```json -Success: OpenInitChannel( - OpenInit( - Attributes { - height: Height { - revision: 1, - height: 225, - }, - port_id: PortId( - "transfer", - ), - channel_id: Some( - ChannelId( - "channel-0", - ), - ), - connection_id: ConnectionId( - "connection-0", - ), - counterparty_port_id: PortId( - "transfer", - ), - counterparty_channel_id: None, - }, - ), -) -``` - -In the following tutorials the __`ibc-0`__ and __`ibc-1`__ chains are setup and configured. - -For clarity, the tutorials run on a setup where the identifiers allocated to the client, connection and channel on __`ibc-0`__ are __`07-tendermint-0`__, __`connection-0`__ and __`channel-0`__ respectively. Identifiers allocated to the client, connection and channel on __`ibc-1`__ are __`07-tendermint-1`__, __`connection-1`__ and __`channel-1`__ respectively. - -Before going over the next sections, please ensure the commands above are executed. - -### Next Steps - -The following sections describe the commands to connect and relay packets between two chains. -You can also use a [simplified approach](./relay-paths/index.md) for managing relaying paths. - diff --git a/guide/src/tutorials/local-chains/index.md b/guide/src/tutorials/local-chains/index.md index d891d1c0a9..0582d86b6b 100644 --- a/guide/src/tutorials/local-chains/index.md +++ b/guide/src/tutorials/local-chains/index.md @@ -1,7 +1,20 @@ -# Tutorial: Relayer with two local chains +# Local chains -In this tutorial we will show how you can test the relayer against two chains using Gaiad manager `gm`. This is the easiest way to get started. +In this tutorial, you will test Hermes against two chains using Gaiad manager `gm`. This is the easiest way to get started. -Using `gm` we will start two [`gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol. +Using `gm` you will start two [`gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol. -Follow the steps in this tutorial section starting with the [Install Gaia](./gaia.md) section. +Make sure that you followed the steps in the [Prerequisites for local chains](../pre-requisites/index.md) section before moving to the [next section](./start-local-chains.md). + +--- + +## Sections + +* **[Start Local Chains](./start-local-chains.md)** + * Start two local chains with `gm` and set up Hermes. + +* **[Add a new relay path](./add-a-new-relay-path.md)** + * Add a relay path between the two chains you started. + +* **[Start relaying](./start-relaying.md)** + * Exchange and relay packets between two local chains. \ No newline at end of file diff --git a/guide/src/tutorials/local-chains/relay-paths/create-new-path.md b/guide/src/tutorials/local-chains/relay-paths/create-new-path.md deleted file mode 100644 index c93b74671b..0000000000 --- a/guide/src/tutorials/local-chains/relay-paths/create-new-path.md +++ /dev/null @@ -1,65 +0,0 @@ -# Create a new path - -Perform client creation, connection and channel handshake to establish a new path between the `transfer` ports on `ibc-0` and `ibc-1` chains. - -```shell -hermes create channel --a-chain ibc-0 --b-chain ibc-1 --a-port transfer --b-port transfer --new-client-connection -``` - -If all the handshakes are performed successfully you should see a message similar to the one below: - -```json -Success: Channel { - ordering: Unordered, - a_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-0", - version: 0, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-0", - ), - connection_id: ConnectionId( - "connection-0", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-0", - ), - }, - b_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-1", - version: 1, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-1", - ), - connection_id: ConnectionId( - "connection-1", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-1", - ), - }, - connection_delay: 0s, - version: Some( - "ics20-1", - ), -} - -``` - -Note that for each side, *a_side* (__ibc-0__) and *b_side* (__ibc-1__) there are a __client_id__, __connection_id__, __channel_id__ and __port_id__. -With all these established, you have [a path that you can relay packets over](./multiple-paths.md). diff --git a/guide/src/tutorials/local-chains/relay-paths/index.md b/guide/src/tutorials/local-chains/relay-paths/index.md deleted file mode 100644 index bcd7dfa3aa..0000000000 --- a/guide/src/tutorials/local-chains/relay-paths/index.md +++ /dev/null @@ -1,12 +0,0 @@ - -# Connect the chains using relay paths - -A relay path refers to a specific channel used to interconnect two chains and over which packets are being sent. - -Hermes can be started to listen for packet events on the two ends of multiple paths and relay packets over these paths. -This can be done over a new path or over existing paths. - -- [Create a new path](./create-new-path.md) -- [Packet relaying on multiple paths](./multiple-paths.md) - -Before proceeding to the sections above, please first, make sure you followed the steps in the [Identifiers section](../identifiers.md) diff --git a/guide/src/tutorials/local-chains/relay-paths/multiple-paths.md b/guide/src/tutorials/local-chains/relay-paths/multiple-paths.md deleted file mode 100644 index d10b5f2e00..0000000000 --- a/guide/src/tutorials/local-chains/relay-paths/multiple-paths.md +++ /dev/null @@ -1,308 +0,0 @@ -# Relay packets on multiple paths - -Hermes can relay packets over all current or future paths between the configured set of chains. - -Follow the steps below to connect three chains together and relay packets between them: - -1. Add the config for the third chain to the existing `$HOME/.gm/gm.toml` file - - ```toml - [global] - add_to_hermes = false - auto_maintain_config = true - extra_wallets = 2 - gaiad_binary = "~/go/bin/gaiad" - hdpath = "" - home_dir = "$HOME/.gm" - ports_start_at = 27000 - validator_mnemonic = "" - wallet_mnemonic = "" - - [global.hermes] - binary = "$HOME/ibc-rs/target/debug/hermes" #change this path according to your setup - config = "./hermes" - log_level = "info" - telemetry_enabled = true - telemetry_host = "127.0.0.1" - telemetry_port = 3001 - - [ibc-0] - ports_start_at = 27010 - - [ibc-1] - ports_start_at = 27020 - - [node-0] - add_to_hermes = true - network = "ibc-0" - ports_start_at = 27030 - - [node-1] - add_to_hermes = true - network = "ibc-1" - ports_start_at = 27040 - - [ibc-2] - ports_start_at = 27050 - - [node-2] - add_to_hermes = true - network = "ibc-2" - ports_start_at = 27060 - ``` - -2. Start the third chain - - ```bash - gm start - ``` -3. Update the `$HOME/.hermes/.config.toml` file - - ```bash - gm hermes config - ``` -4. Associate the keys to the new chain - - ```bash - gm hermes keys - ``` -5. Check the status of the chains - - ```bash - gm status - ``` - -6. Create a channel between `ibc-0` and `ibc-1`. Since this is the first time - we're connecting these two chains, we'll need to spin up a client and a - connection between them as well. The `create channel` command gives us the - convenient option to create a client and a connection. Keep in mind that this - is not the default behavior of `create channel`, but in this case we're - making an exception. Execute the following command: - - ```shell - hermes create channel --a-chain ibc-0 --b-chain ibc-1 --a-port transfer --b-port transfer --new-client-connection - ``` - - Then respond 'yes' to the prompt that pops up. Once the command has run to - completion, you should see the following among the output logs: - - ```json - (...) - - Success: Channel { - ordering: Unordered, - a_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-0", - version: 0, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-0", - ), - connection_id: ConnectionId( - "connection-0", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-0", - ), - }, - b_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-1", - version: 1, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-0", - ), - connection_id: ConnectionId( - "connection-0", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-0", - ), - }, - connection_delay: 0s, - version: Some( - "ics20-1", - ), - } - ``` - - Note that the channel identifier on both `ibc-0` and `ibc-1` is `channel-0`. - -7. Create a channel between `ibc-1` and `ibc-2` using the structure of the - previous invocation we used to create a channel between `ibc-0` and `ibc-1`: - - ```shell - hermes create channel --a-chain ibc-1 --b-chain ibc-2 --a-port transfer --b-port transfer --new-client-connection - ``` - - ```json - (...) - - Success: Channel { - ordering: Unordered, - a_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-1", - version: 1, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-1", - ), - connection_id: ConnectionId( - "connection-1", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-1", - ), - }, - b_side: ChannelSide { - chain: ProdChainHandle { - chain_id: ChainId { - id: "ibc-2", - version: 2, - }, - runtime_sender: Sender { .. }, - }, - client_id: ClientId( - "07-tendermint-0", - ), - connection_id: ConnectionId( - "connection-0", - ), - port_id: PortId( - "transfer", - ), - channel_id: ChannelId( - "channel-0", - ), - }, - connection_delay: 0s, - version: Some( - "ics20-1", - ), - } - ``` - - Note that the channel identifier on `ibc-1` is `channel-1`, and on `ibc-2` it is `channel-0`. - -8. Start Hermes using the `start` command: - - ```shell - hermes start - ``` - - Hermes will first relay the pending packets that have not been relayed and then - start passive relaying by listening to and acting on packet events. - -9. In a separate terminal, use the `ft-transfer` command to send: - - - Two packets from `ibc-0` to `ibc-1` from source channel `channel-0` - - ```shell - hermes tx ft-transfer --dst-chain ibc-1 --src-chain ibc-0 --src-port transfer --src-channel channel-0 --amount 9999 --timeout-seconds 1000 --number-msgs 2 - ``` - - ```json - Success: [ - SendPacket( - SendPacket { - height: revision: 0, height: 3056, - packet: PortId("transfer") ChannelId("channel-0") Sequence(3), - }, - ), - SendPacket( - SendPacket { - height: revision: 0, height: 3056, - packet: PortId("transfer") ChannelId("channel-0") Sequence(4), - }, - ), - ] - ``` - - - Two packets from `ibc-1` to `ibc-2` from source channel `channel-1` - - ```shell - hermes tx ft-transfer --dst-chain ibc-2 --src-chain ibc-1 --src-port transfer --src-channel channel-1 --amount 9999 --timeout-seconds 1000 --number-msgs 2 - ``` - - ```json - Success: [ - SendPacket( - SendPacket { - height: revision: 1, height: 3076, - packet: PortId("transfer") ChannelId("channel-1") Sequence(3), - }, - ), - SendPacket( - SendPacket { - height: revision: 1, height: 3076, - packet: PortId("transfer") ChannelId("channel-1") Sequence(4), - }, - ), - ] - ``` - -10. Observe the output on the relayer terminal, verify that the send events are processed, and that the `recv_packets` are sent out. - - ```text - (...) - - INFO ibc_relayer::link: [ibc-0 -> ibc-1] result events: - UpdateClientEv(ev_h:1-3048, 07-tendermint-0(0-3057), ) - WriteAcknowledgementEv(h:1-3048, seq:3, path:channel-0/transfer->channel-0/transfer, toh:1-4045, tos:0)) - WriteAcknowledgementEv(h:1-3048, seq:4, path:channel-0/transfer->channel-0/transfer, toh:1-4045, tos:0)) - INFO ibc_relayer::link: [ibc-0 -> ibc-1] success - - (...) - - INFO ibc_relayer::link: [ibc-1 -> ibc-0] clearing old packets - INFO ibc_relayer::link: [ibc-1 -> ibc-0] received from query_txs [] - INFO ibc_relayer::link: [ibc-1 -> ibc-0] finished clearing pending packets - INFO ibc_relayer::link: [ibc-1 -> ibc-0] generate messages from batch with 2 events - INFO ibc_relayer::link: [ibc-1 -> ibc-0] scheduling op. data with 2 msg(s) for Destination chain (height 1-3049) - INFO ibc_relayer::link: [ibc-1 -> ibc-0] relay op. data to Destination, proofs height 1-3048, (delayed by: 2.154603ms) [try 1/10] - INFO ibc_relayer::link: [ibc-1 -> ibc-0] prepending Destination client update @ height 1-3049 - INFO ibc_relayer::link: [ibc-1 -> ibc-0] assembled batch of 3 message(s) - INFO ibc_relayer::link: [ibc-1 -> ibc-0] result events: - UpdateClientEv(ev_h:0-3059, 07-tendermint-0(1-3049), ) - AcknowledgePacketEv(h:0-3059, seq:3, path:channel-0/transfer->channel-0/transfer, toh:1-4045, tos:0)) - AcknowledgePacketEv(h:0-3059, seq:4, path:channel-0/transfer->channel-0/transfer, toh:1-4045, tos:0)) - INFO ibc_relayer::link: [ibc-1 -> ibc-0] success - - (...) - ``` - -11. Query the unreceived packets and acknowledgments on `ibc-1` and `ibc-2` from a different terminal: - - ```shell - hermes query packet pending-sends --chain ibc-1 --port transfer --channel channel-0 - hermes query packet pending-acks --chain ibc-0 --port transfer --channel channel-0 - hermes query packet pending-sends --chain ibc-2 --port transfer --channel channel-0 - hermes query packet pending-acks --chain ibc-1 --port transfer --channel channel-1 - ``` - - If everything went well, each of these commands should result in: - - ``` - Success: [] - ``` diff --git a/guide/src/tutorials/local-chains/start.md b/guide/src/tutorials/local-chains/start-local-chains.md similarity index 61% rename from guide/src/tutorials/local-chains/start.md rename to guide/src/tutorials/local-chains/start-local-chains.md index 68a67fec01..d41fc18c22 100644 --- a/guide/src/tutorials/local-chains/start.md +++ b/guide/src/tutorials/local-chains/start-local-chains.md @@ -1,132 +1,93 @@ # Start the local chains -In this chapter, you will learn how to spawn two Gaia chains, and use Hermes to relay packets between them. +In this chapter, you will learn how to spawn two Gaia chains, and use Hermes to relay packets between them. The topology of the network will look like this: -To spawn the chains and configure Hermes accordingly, we will make use of Gaiad Manager `gm` that we installed in the last section [Install Gaiad Manager](gaiad-manager.md) +```mermaid +flowchart LR + A((ibc-0))---B((ibc-1)) +``` -### Stop existing `gaiad` processes +To spawn the chains and configure Hermes accordingly, we will make use of Gaiad Manager `gm` that we installed in the last section [Install Gaiad Manager](../pre-requisites/gaiad-manager.md). -If this is not the first time you are running the script, you can manually stop the two gaia instances executing the following command to kill all `gaiad` processes: +--- -```shell -killall gaiad -``` +### Reset your configuration and start the chains -> __NOTE__: If you have any `Docker` containers running that might be using the same ports as `gaiad` (e.g. port 27010-27012), please ensure you stop them first before proceeding to the next step. +Make sure you have the `{{#template ../../templates/path/gm/default_path}}` that we configured in the previous section [Install Gaiad Manager](../pre-requisites/gaiad-manager.md). If this is not the first time you are running the script, you can manually stop the two gaia instances executing the following command to kill all `gaiad` processes: -Make sure that `$HOME/.gm` does not contain any `ibc-*` or `node-*` file. Otherwise, remove them manually with `gm rm` or simply : +```shell +{{#template ../../templates/commands/gm/stop}} +``` +Then, reset the configuration of every node and every chain with: ```shell - rm -r $HOME/.gm/node-* - rm -r $HOME/.gm/ibc-* +rm -r $HOME/.gm/node-* +rm -r $HOME/.gm/ibc-* ``` -### Start the chains with `gm` -Make sure you have the `$HOME/.gm/gm.toml` that we configured in the previous section [Install Gaiad Manager](gaiad-manager.md) and run the `gm` command below to start the chains. +> __NOTE__: If you have any `Docker` containers running that might be using the same ports as `gaiad` (e.g. port 27010-27012), please ensure you stop them first before proceeding to the next step. -```shell -gm start +Finally, start the chains with the `start` command. + +```bash +{{#template ../../templates/commands/gm/start}} ``` -This configures and starts two __`gaiad`__ instances, one named __`ibc-0`__ and the other __`ibc-1`__ +This configures and starts two __`gaiad`__ instances, one named __`ibc-0`__ and the other named __`ibc-1`__: ```mermaid - graph TD - A[gm] -->|start| C(start chains) - C -->|gaiad| D[ibc-0] - C -->|gaiad| E[ibc-1] +graph TD + A[gm] -->|start| C(start chains) + C -->|gaiad| D[ibc-0] + C -->|gaiad| F[ibc-1] ``` -If the command runs successfully you should see a message similar to the one below in the terminal: +If the command runs successfully, it should output something similar to: ```shell - Creating network1 config... - network1 started, PID: 99468, LOG: $HOME/.gm/network1/log - Creating network2 config... - network2 started, PID: 99538, LOG: $HOME/.gm/network2/log - Creating ibc-0 config... - ibc-0 started, PID: 99645, LOG: $HOME/.gm/ibc-0/log - Creating ibc-1 config... - ibc-1 started, PID: 99750, LOG: $HOME/.gm/ibc-1/log +Creating ibc-0 config... +ibc-0 started, PID: 11244, LOG: $HOME/.gm/ibc-0/log +Creating ibc-1 config... +ibc-1 started, PID: 11796, LOG: $HOME/.gm/ibc-1/log +Creating node-0 config... +node-0 started, PID: 12342, LOG: $HOME/.gm/node-0/log +Creating node-1 config... +node-1 started, PID: 12885, LOG: $HOME/.gm/node-1/log ``` -Run the below command to check the status of the chains + +Run the following command to check the status of the chains: ```bash -gm status +{{#template ../../templates/commands/gm/status}} +``` + +If the command is successful, you should see a message similar to: ``` +NODE PID RPC APP GRPC HOME_DIR +ibc-0 11244 27010 27011 27012 $HOME/.gm/ibc-0 + node-0 12342 27030 27031 27032 $HOME/.gm/node-0 +ibc-1 11796 27020 27021 27022 $HOME/.gm/ibc-1 + node-1 12885 27040 27041 27042 $HOME/.gm/node-1 +``` + ### Configuration file -Gaiad Manager `gm` takes care of creating the configuration file. Run the command below to create the `$HOME/.hermes/config.toml` file +Gaiad Manager `gm` takes care of creating the configuration file. Run the command below to create the `$HOME/.hermes/config.toml` file: ```bash -gm hermes config +{{#template ../../templates/commands/gm/hermes_config}} ``` -Please check the [`Configuration`](../../config.md) section for more information about the relayer configuration file. +>__NOTE__: You can visit the [`Configuration`](../../documentation/configuration/index.md) section for more information about the configuration file. -Based on the `gm.toml` we created in the previous section [Install Gaiad Manager](gaiad-manager.md), your `$HOME/.hermes/config.toml` file should look like below : +Based on the `gm.toml` we created in the previous section [Install Gaiad Manager](../pre-requisites/gaiad-manager.md), your `$HOME/.hermes/config.toml` file should look like below : __config.toml__ ```toml -[global] -log_level = 'info' - -[mode] - -[mode.clients] -enabled = true -refresh = true -misbehaviour = true - -[mode.connections] -enabled = true - -[mode.channels] -enabled = true - -[mode.packets] -enabled = true -clear_interval = 100 -clear_on_start = true -tx_confirmation = true - -[telemetry] -enabled = true -host = '127.0.0.1' -port = 3001 - -[[chains]] -id = 'ibc-0' -rpc_addr = 'http://localhost:27030' -grpc_addr = 'http://localhost:27032' -websocket_addr = 'ws://localhost:27030/websocket' -rpc_timeout = '15s' -account_prefix = 'cosmos' -key_name = 'wallet' -store_prefix = 'ibc' -gas_price = { price = 0.01, denom = 'stake' } -max_gas = 10000000 -clock_drift = '5s' -trusting_period = '14days' -trust_threshold = { numerator = '1', denominator = '3' } - -[[chains]] -id = 'ibc-1' -rpc_addr = 'http://localhost:27040' -grpc_addr = 'http://localhost:27042' -websocket_addr = 'ws://localhost:27040/websocket' -rpc_timeout = '15s' -account_prefix = 'cosmos' -key_name = 'wallet' -store_prefix = 'ibc' -gas_price = { price = 0.01, denom = 'stake' } -max_gas = 10000000 -clock_drift = '5s' -trusting_period = '14days' -trust_threshold = { numerator = '1', denominator = '3' } +{{#template ../../templates/files/hermes/local-chains/config.toml}} ``` ### Adding private keys to the chains @@ -136,10 +97,13 @@ trust_threshold = { numerator = '1', denominator = '3' } To see the keys generated by `gm`, run the command below ```bash -gm keys +{{#template ../../templates/commands/gm/keys}} ``` This will generate an output similar to the one below (albeit all on the same line): + +
{{#template ../../templates/commands/gm/keys}} output + ``` "$HOME/go/bin/gaiad" keys list --keyring-backend test --keyring-dir "$HOME/.gm/ibc-0" @@ -192,26 +156,33 @@ mnemonic: "wish burden unfair subway club pulp wood helmet whip decline between [] ``` +
+ Next, we will need to associate a private key with chains `ibc-0` and `ibc-1` which `hermes` will use to sign transactions. ```bash -gm hermes keys +{{#template ../../templates/commands/gm/hermes_keys}} ``` If successful, the command should show an output similar to: ``` -SUCCESS: Added key testkey ([ADDRESS]) on [CHAIN ID] chain +SUCCESS Added key 'wallet' (cosmos1qsl5sq48r7xdfwq085x9pnlfu9ul5seufu3n03) on chain ibc-0 +SUCCESS Added key 'wallet2' (cosmos1haaphqucg2u9g8gwgv6z8jzegvca85r4d7yqh9) on chain ibc-0 +SUCCESS Added key 'wallet1' (cosmos1cgjf7m9txsxf2pdekxk60ll6xusx0heznqsnxn) on chain ibc-0 +SUCCESS Added key 'wallet' (cosmos1zp3t2rp7tjr23wchp36lmw7vhk77gtvvc7lc5s) on chain ibc-1 +SUCCESS Added key 'wallet2' (cosmos1644x9c8pyfwcmg43ch2u3vr6hl4rkmkz2weq39) on chain ibc-1 +SUCCESS Added key 'wallet1' (cosmos1dsrj2uqjvtssenkwperuvfkgkg2xvmydvpzswy) on chain ibc-1 ``` > __TROUBLESHOOTING__: -> - If the command does not out output anything, make sure the path to Hermes' binary is set in `$HOME/.gm/gm.toml`. +> - If the command does not out output anything, make sure the path to Hermes' binary is set in `{{#template ../../templates/path/gm/default_path}}`. -### $HOME/.gm directory +### The `$HOME/.gm` directory -This directory is creted when you install `gm` and the binaries are stored here but when we start the chains, all the related files and folders are stored here as well. +This directory is created when you install `gm` and the binaries are stored here but when we start the chains, all the related files and folders are stored here as well. -The $HOME/.gm directory has a tree structure similar to the one below: +The `$HOME/.gm` directory has a tree structure similar to the one below: ```shell .gm @@ -256,18 +227,17 @@ The $HOME/.gm directory has a tree structure similar to the one below: ├── keyring-test ├── log └── pid - ``` > __Tip__: You can use the command `tree ./data/ -L 2` to view the folder structure above -### $HOME/.hermes directory +### The `$HOME/.hermes` directory By the default `hermes` expects the configuration file to be in the __`$HOME/.hermes`__ folder. It also stores the private keys for each chain in this folder as outlined in the [Keys](../../commands/keys/index.md) section. -After executing `gm start`, this is how the folder should look like: +After executing `{{#template ../../templates/commands/gm/start}}`, this is how the folder should look like: ```shell $HOME/.hermes/ @@ -281,8 +251,9 @@ $HOME/.hermes/ └── testkey.json ``` -#### Next Steps +--- + +## Next Steps + +[The next section](./add-a-new-relay-path.md) describes how clients, connections and channels are created and how their identifiers are assigned. -[The next section](./identifiers.md) describes how identifers for clients, connections and channels -are allocated, and will walk you through how to pre-allocate some identifers -to help matching them with their corresponding chains for the purpose of this tutorial. diff --git a/guide/src/tutorials/local-chains/start-relaying.md b/guide/src/tutorials/local-chains/start-relaying.md new file mode 100644 index 0000000000..7fd10f7da6 --- /dev/null +++ b/guide/src/tutorials/local-chains/start-relaying.md @@ -0,0 +1,136 @@ +# Start relaying + +In the [previous section](./add-a-new-relay-path.md), you created clients, established a connection between them, and opened a channel on top of it. Now you can start relaying on this path. + +__Relay path__: +```mermaid +flowchart LR + A((ibc-0))---B(transfer
channel-0)---C(transfer
channel-0)---D((ibc-1)) +``` + +--- + +## Query balances + +Use the following commands to query balances on your local chains: + +- Balances on ibc-0: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27030 home=~/.gm/ibc-0 wallet=wallet}} + ``` + +- Balances on ibc-1: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27040 home=~/.gm/ibc-1 wallet=wallet}} + ``` + +> __NOTE__ the RPC addresses used in the two commands above are configured in `~/.hermes/config.toml` file. It can also be found with `{{#template ../../templates/commands/gm/status}}` + +At this point in the tutorial, the two commands should output something similar to: + +``` +balances: +- amount: "100000000" + denom: samoleans +- amount: "99994088" + denom: stake +pagination: + next_key: null + total: "0" +``` +>__NOTE__: Some `stake` tokens were used during the connection and channel handshakes. + +## Exchange packets + +Now, let's exchange `samoleans` between two chains. + +- Open a new terminal and start Hermes using the `start` command : + + ```shell + {{#template ../../templates/commands/hermes/start}} + ``` + Hermes will first relay the pending packets that have not been relayed and then start passively relaying by listening for and acting on packet events. + +- In a separate terminal, use the `ft-transfer` command to send `100000 samoleans` from ibc-0 to ibc-1 over channel-0: + ```shell + {{#template ../../templates/commands/hermes/transfer dst-chain=ibc-1 src-chain=ibc-0 src-port=transfer src-channel=channel-0 amount=100000 timeout-seconds=1000}} + ``` + +- Wait a few seconds, then query balances on `ibc-1` and `ibc-0`. You should observe something similar to: + - Balances at ibc-0: + ``` + balances: + - amount: "99900000" + denom: samoleans + - amount: "99992054" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances at ibc-1: + ``` + balances: + - amount: "100000" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99989196" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The samoleans were transferred to ibc-1 and are visible under the denomination `ibc/C1840...`. + +- Transfer back these tokens to ibc-0: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-1 src-chain=ibc-0 src-port=transfer src-channel=channel-0 amount=100000 timeout-seconds=10000 --denom ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199}} + ``` +- Wait a few seconds then query balances on `ibc-1` and `ibc-0` again. You should observe something similar to: + - Balances on ibc-0: + ``` + balances: + - amount: "100000000" + denom: samoleans + - amount: "99987927" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances on ibc-1: + ``` + balances: + - amount: "0" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99983879" + denom: stake + pagination: + next_key: null + total: "0" + ``` +- Open your browser and open `http://localhost:3001/metrics`. At this point, you should observe that the `wallet_balance` metric corresponds to what you observed in the previous step. All the metrics can be useful and are described in the [Telemetry](../../documentation/telemetry/index.md) section. We will describe a way to use them in the tutorial [Relaying in production](../production/index.md). + +## Stop relaying and stop the chains + +- Stop Hermes by pressing `Ctrl+C` on the terminal running `{{#template ../../templates/commands/hermes/start}}`. + +- Stop the chains with `{{#template ../../templates/commands/gm/stop}}`. + +--- + +## Next steps + +In this tutorial, you learned the basics of relaying by: +- Creating clients on two chains. +- Establishing a connection between them. +- Opening a channel. +- Visualizing your network. +- Exchanging packets. + +In the [next tutorial](../more-chains/index.md), you will learn how to relay between multiple chains with multiple instances. diff --git a/guide/src/tutorials/more-chains/build-the-topology.md b/guide/src/tutorials/more-chains/build-the-topology.md new file mode 100644 index 0000000000..5fcec1f719 --- /dev/null +++ b/guide/src/tutorials/more-chains/build-the-topology.md @@ -0,0 +1,204 @@ +# Build the topology + +At this point in the tutorial, you should have four chains running and Hermes correctly configured. You can perform a `health-check` with the command : + +```shell +{{#template ../../templates/commands/hermes/health_check}} +``` + +If the command runs successfully, it should output something similar to: +``` + 2022-08-23T15:54:58.150005Z INFO ThreadId(01) using default configuration from '$HOME/.hermes/config.toml' + 2022-08-23T15:54:58.150179Z INFO ThreadId(01) [ibc-0] performing health check... + 2022-08-23T15:54:58.163298Z INFO ThreadId(01) chain is healthy chain=ibc-0 + 2022-08-23T15:54:58.163323Z INFO ThreadId(01) [ibc-1] performing health check... + 2022-08-23T15:54:58.169132Z INFO ThreadId(01) chain is healthy chain=ibc-1 + 2022-08-23T15:54:58.169154Z INFO ThreadId(01) [ibc-2] performing health check... + 2022-08-23T15:54:58.178418Z INFO ThreadId(01) chain is healthy chain=ibc-2 + 2022-08-23T15:54:58.178445Z INFO ThreadId(01) [ibc-3] performing health check... + 2022-08-23T15:54:58.184615Z INFO ThreadId(01) chain is healthy chain=ibc-3 + SUCCESS performed health check for all chains in the config +``` + +In the following tutorial, we will connect all of these chains in a full mesh topology, then use `Packet filters` to simulate the topology given at the beginning of the [previous section](./start-local-chains.md). + +> __NOTE__: It is also possible to only create the channels that you want. However, in production, anyone can open channels and recreate a fully-connected topology. + +--- + +## Connect all the chains + +Execute the following command: +```shell +{{#template ../../templates/commands/gm/hermes_cc}} +``` + +If this command runs successfully, it should output the following: + +```shell +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-0 b-chain=ibc-1 a-port=transfer b-port=transfer}} +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-0 b-chain=ibc-2 a-port=transfer b-port=transfer}} +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-0 b-chain=ibc-3 a-port=transfer b-port=transfer}} +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-1 b-chain=ibc-2 a-port=transfer b-port=transfer}} +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-1 b-chain=ibc-3 a-port=transfer b-port=transfer}} +{{#template ../../templates/commands/hermes/create_channel_new_client binary="$HOME/ibc-rs/target/release/hermes" a-chain=ibc-2 b-chain=ibc-3 a-port=transfer b-port=transfer}} +``` + +Executing these commands will: +* For every pair of chains, create a client on both chain tracking the state of the counterparty chain. +* Create a connection between these two clients. +* Create a `transfer` channel over this connection. + +Use the flag `--exec` flag to execute these commands: + +```shell +{{#template ../../templates/commands/gm/hermes_cc_exec}} +``` + +At this point, your network should be fully connected. It is now time to filter channels. The following chart shows the current state of the network. The channels that we want to filter out are filled in red while the channels we want to relay on are filled in green: + +__Network topology__ +```mermaid +flowchart TD + ibc0((ibc-0)) + ibc0ibc1[[channel-0]] + ibc0ibc2[[channel-1]] + ibc0ibc3[[channel-2]] + + ibc1((ibc-1)) + ibc1ibc0[[channel-0]] + ibc1ibc2[[channel-1]] + ibc1ibc3[[channel-2]] + + ibc2((ibc-2)) + ibc2ibc0[[channel-0]] + ibc2ibc1[[channel-1]] + ibc2ibc3[[channel-2]] + + ibc3((ibc-3)) + ibc3ibc0[[channel-0]] + ibc3ibc1[[channel-1]] + ibc3ibc2[[channel-2]] + + classDef deny fill:#AA0000,color:#000000; + classDef allow fill:#00AA00,color:#000000; + class ibc0ibc1 allow; + class ibc1ibc0 allow; + class ibc0ibc3 allow; + class ibc3ibc0 allow; + class ibc2ibc1 allow; + class ibc1ibc2 allow; + class ibc2ibc3 allow; + class ibc3ibc2 allow; + + + class ibc1ibc3 deny; + class ibc3ibc1 deny; + class ibc0ibc2 deny; + class ibc2ibc0 deny; + + ibc0---ibc0ibc1---ibc1ibc0---ibc1 + ibc0---ibc0ibc2---ibc2ibc0---ibc2 + ibc0---ibc0ibc3---ibc3ibc0---ibc3 + ibc1---ibc1ibc2---ibc2ibc1---ibc2 + ibc1---ibc1ibc3---ibc3ibc1---ibc3 + ibc2---ibc2ibc3---ibc3ibc2---ibc3 +``` + +You can verify that everything is correct with the commands: + +```shell +{{#template ../../templates/commands/hermes/query_channels_show_counterparty chain=ibc-0}} +{{#template ../../templates/commands/hermes/query_channels_show_counterparty chain=ibc-1}} +{{#template ../../templates/commands/hermes/query_channels_show_counterparty chain=ibc-2}} +{{#template ../../templates/commands/hermes/query_channels_show_counterparty chain=ibc-3}} +``` + +Which should normally output: + +``` +ibc-0: transfer/channel-0 --- ibc-1: transfer/channel-0 +ibc-0: transfer/channel-1 --- ibc-2: transfer/channel-0 +ibc-0: transfer/channel-2 --- ibc-3: transfer/channel-0 + +ibc-1: transfer/channel-0 --- ibc-0: transfer/channel-0 +ibc-1: transfer/channel-1 --- ibc-2: transfer/channel-1 +ibc-1: transfer/channel-2 --- ibc-3: transfer/channel-1 + +ibc-2: transfer/channel-0 --- ibc-0: transfer/channel-1 +ibc-2: transfer/channel-1 --- ibc-1: transfer/channel-1 +ibc-2: transfer/channel-2 --- ibc-3: transfer/channel-2 + +ibc-3: transfer/channel-0 --- ibc-0: transfer/channel-2 +ibc-3: transfer/channel-1 --- ibc-1: transfer/channel-2 +ibc-3: transfer/channel-2 --- ibc-2: transfer/channel-2 +``` + +## Add packet filters + +Let's use packet filters to relay only on the green paths specified in the chart. In order to add filters, open your default configuration file `$HOME/.hermes/config.toml` and add: +- Under `ibc-0`'s config: + ``` + [chains.packet_filter] + policy = 'allow' + list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-2'], + ] + ``` +- Under `ibc-1`'s config: + ``` + [chains.packet_filter] + policy = 'allow' + list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-1'], + ] + ``` +- Under `ibc-2`'s config: + ``` + [chains.packet_filter] + policy = 'allow' + list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-2'], + ] + ``` +- Under `ibc-3`'s config: + ``` + [chains.packet_filter] + policy = 'allow' + list = [ + ['transfer', 'channel-0'], + ['transfer', 'channel-2'], + ] + ``` + +> __NOTE__: It is also possible to use a `deny` policy to filter out the channels you do not want to relay on. However, if other channels exist or are created, the relayer will also relay on them. + +At this point, your config file should look like this: +
config.toml + +``` +{{#template ../../templates/files/hermes/more-chains/config_with_filters.toml}} +``` + +
+ +It is also possible to check that the configuration file is valid with the command: + +```shell +{{#template ../../templates/commands/hermes/config_validate}} +``` + +If the command runs successfully, the output should be: + +``` +SUCCESS "configuration is valid" +``` + +--- + +## Next Steps + +The [following section](./start-relaying.md) describes how to relay packets between any chain with this topology. diff --git a/guide/src/tutorials/more-chains/concurrent-instances.md b/guide/src/tutorials/more-chains/concurrent-instances.md new file mode 100644 index 0000000000..518e793372 --- /dev/null +++ b/guide/src/tutorials/more-chains/concurrent-instances.md @@ -0,0 +1,248 @@ +# Add new instances of Hermes + +In the previous section, you attempted a direct transfer between `ibc-1` and `ibc-3` which failed because your current instance of Hermes does not relay on that path. + +In the following section, you will start new instances of Hermes to relay on the paths which are currently disabled: + +```mermaid +flowchart LR +A((ibc-0))---B[[channel-1]]---C[[channel-0]]---D((ibc-2)) + +E((ibc-1))---G[[channel-2]]---H[[channel-1]]---F((ibc-3)) + +classDef deny fill:#AA0000,color:#000000; + +class B deny; +class C deny; +class G deny; +class H deny; +``` + +Running multiple instances of Hermes can have many advantages and disadvantages. It allows for fine-grained control over every channel and can be more stable than running a single instance. However, you will also need to manage more wallets. + +--- + + +## Create a new config file + +First, you will have to create a new configuration file with: +- New packets filters. + + In order to enable the new paths. + +- Different wallets. + + **Two instances of Hermes can not share the same wallet.** + +- A different telemetry port. + + **Two processes can not share the same port for any of their services.** + +Create the following configuration file at `$HOME/hermes_second_instance.toml`: + +__hermes_second_instance.toml__ + +```toml +{{#template ../../templates/files/hermes/more-chains/hermes_second_instance.toml}} +``` + +In order to make use of this config, specify it with the `--config` flag: + +```shell +hermes --config $HOME/hermes_second_instance.toml +``` + +## Query pending packets +Let's find the packet that was lost in the first step of the [previous section](./start-relaying.md) with the `query packet` command: + +```shell +{{#template ../../templates/commands/hermes/query_packet_pending chain=ibc-1 port=transfer channel=channel-2}} +``` + +>__NOTE__: You do not need to specify the configuration file as long as `ibc-1` and `ibc-3` are in the default config file. + +If the command runs succesfully, it should output: + +``` +SUCCESS Summary { + src: PendingPackets { + unreceived_packets: [ + Sequence( + 1, + ), + ], + unreceived_acks: [], + }, + dst: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, +} +``` + +## Clear the packet +Now that we have retrieved this packet, let's clear it manually with the command `hermes clear packets`: + +```shell +{{#template ../../templates/commands/hermes/optional_config_flag/clear_packets config=$HOME/hermes_second_instance.toml chain=ibc-1 port=transfer channel=channel-2}} +``` +>__NOTE__: We are using the second config to avoid using the same wallets as the running instance of the relayer. You could also simply use the `key-name` and `counterparty-key-name` flags to set another wallet. If you do not use it, you will observe a few `account_sequence_mismatch` errors on the terminal running `hermes start` but hermes will automatically recover. + +If the command runs succesfully, it should output: + +``` +SUCCESS [ + UpdateClient( + cs_h: 07-tendermint-1(1-364), + ), + WriteAcknowledgement( + WriteAcknowledgement - seq:1, path:channel-2/transfer->channel-1/transfer, toh:no timeout, tos:Timestamp(2022-08-29T18:29:44.733494709Z)), + ), + UpdateClient( + cs_h: 07-tendermint-2(3-365), + ), + AcknowledgePacket( + AcknowledgePacket - seq:1, path:channel-2/transfer->channel-1/transfer, toh:no timeout, tos:Timestamp(2022-08-29T18:29:44.733494709Z)), + ), +] +``` + +>__NOTE__: It can also output a TimeoutPacket if you execute it after the packet times out (10000 seconds in this case). + +You can verify that the packet was correctly relayed by querying balances or directly querying packets: +```shell +{{#template ../../templates/commands/hermes/query_packet_pending chain=ibc-1 port=transfer channel=channel-2}} +``` + +If the command runs successfully, it should output: + +``` +SUCCESS Summary { + src: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, + dst: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, +} +``` + +As you can see, there is currently no stuck packet between `ibc-1` and `ibc-3`. + +## Make stuck packets + +For the sake of learning, let's make new stuck packets on the `ibc-0<>ibc-2` channel and the `ibc-1<>ibc-3` channel. + +```shell +{{#template ../../templates/commands/hermes/transfer dst-chain=ibc-3 src-chain=ibc-1 src-port=transfer src-channel=channel-2 amount=1000000 timeout-seconds=10000}} +{{#template ../../templates/commands/hermes/transfer dst-chain=ibc-2 src-chain=ibc-0 src-port=transfer src-channel=channel-1 amount=1000000 timeout-seconds=10000}} +``` + +If both commands run successfully, they should output a `SUCCESS` message. + +Now, let's verify that these packets are indeed stuck with the `query packet` command: + +- On `ibc-0`: + ```shell + {{#template ../../templates/commands/hermes/query_packet_pending chain=ibc-0 port=transfer channel=channel-1}} + ``` + + Which should output: + + ``` + SUCCESS Summary { + src: PendingPackets { + unreceived_packets: [ + Sequence( + 1, + ), + ], + unreceived_acks: [], + }, + dst: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, + } + ``` + + +- On `ibc-1`: + ```shell + {{#template ../../templates/commands/hermes/query_packet_pending chain=ibc-1 port=transfer channel=channel-2}} + ``` + + Which should output: + + ``` + SUCCESS Summary { + src: PendingPackets { + unreceived_packets: [ + Sequence( + 2, + ), + ], + unreceived_acks: [], + }, + dst: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, + } + ``` + +You have pending packets on the two paths filtered out by our running instance. + +>__NOTE__: You can also verify that Hermes is still relaying on the other paths by sending a packet from `ibc-1` to `ibc-2`: +> +>```shell +>{{#template ../../templates/commands/hermes/transfer dst-chain=ibc-2 src-chain=ibc-1 src-port=transfer src-channel=channel-1 amount=1000000 timeout-seconds=10000}} +>``` +> +>Wait a few seconds then verify that no packet is pending with: +>```shell +>{{#template ../../templates/commands/hermes/query_packet_pending chain=ibc-1 port=transfer channel=channel-1}} +>``` + + +## Start your second instance to clear packets + +Instead of clearing packets manually again, you can just start Hermes with the [new config file you created](#create-a-new-config-file) in a new terminal: + +```shell +{{#template ../../templates/commands/hermes/optional_config_flag/start config=$HOME/hermes_second_instance.toml}} +``` + +At launch, Hermes will clear pending packets before moving into passive mode. + +- Wait a few seconds. You should observe logs produced on the terminal running the second instance of Hermes. + +- Query for pending packets at `ibc-0` on `channel-1` and `ibc-1` on `channel-2` again with the `query packet pending` command. Both should output: + ``` + SUCCESS Summary { + src: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, + dst: PendingPackets { + unreceived_packets: [], + unreceived_acks: [], + }, + } + ``` + +You can now send packets between any pair of chains. One of your two instances will relay it. Feel free to exchange more packets and observe the logs. + +## Stop relaying and stop the chains + +- Stop Hermes by pressing `Ctrl+C` on the terminals running `{{#template ../../templates/commands/hermes/start}}`. + +- Stop the chains with `{{#template ../../templates/commands/gm/stop}}`. + +--- + +## Next Steps + +In the [next tutorial](../production/index.md), you will learn how to set up Hermes in production. diff --git a/guide/src/tutorials/more-chains/index.md b/guide/src/tutorials/more-chains/index.md new file mode 100644 index 0000000000..34692c7236 --- /dev/null +++ b/guide/src/tutorials/more-chains/index.md @@ -0,0 +1,26 @@ +# Even more local chains + +In this tutorial, you will test Hermes against four chains using Gaiad manager `gm` connected in an arbitrary topology of IBC channels. + +Using `gm` you will start four [`gaia`](https://github.com/cosmos/gaia) chains that support the `IBC` protocol. + +Make sure that you followed the steps in the [Prerequisites for local chains](../pre-requisites/index.md) section before moving to the [next section](./start-local-chains.md). + + +--- + +## Sections + +* **[Start Local Chains](./start-local-chains.md)** + * Start four local chains with `gm` and set up Hermes. + +* **[Build the topology](./build-the-topology.md)** + * Add a relay path between every chain and relay on an arbitrary topology with packet filters. + +* **[Start relaying](./start-relaying.md)** + * Exchange and relay packets between these chains. + +* **[Add new instances of Hermes](./concurrent-instances.md)** + * Add new instances of Hermes to start relaying on the paths filtered out by the first instance. + + diff --git a/guide/src/tutorials/more-chains/start-local-chains.md b/guide/src/tutorials/more-chains/start-local-chains.md new file mode 100644 index 0000000000..90c79671ea --- /dev/null +++ b/guide/src/tutorials/more-chains/start-local-chains.md @@ -0,0 +1,277 @@ +# Start the local chains + +In this chapter, you will learn how to spawn four Gaia chains, connect them in an arbitrary topology and use Hermes to transfer tokens between them. + +```mermaid +flowchart LR + ibc0((ibc-0)) + ibc1((ibc-1)) + ibc2((ibc-2)) + ibc3((ibc-3)) + + ibc0---ibc1 + ibc1---ibc2 + ibc2---ibc3 + ibc0---ibc3 + +``` + +As for the [Local chains tutorial](../local-chains/index.md), we will make use of Gaiad Manager `gm` that we installed in [Install Gaiad Manager](../pre-requisites/gaiad-manager.md). + +--- + +### Reset your configuration + +First, make sure that no chain is currently running by killing all `gaiad` processes. + +```shell +{{#template ../../templates/commands/gm/stop}} +``` + +Then, make sure that your folder `$HOME/.gm` does not contain any `ibc-*` or `node-*` file. You can remove them with + +```shell +rm -r $HOME/.gm/node-* +rm -r $HOME/.gm/ibc-* +``` + +Copy and paste the configuration below to `{{#template ../../templates/path/gm/default_path}}` and set Hermes' binary path according to your setup. The following contains the configuration of 4 IBC-enabled chains. + +__gm.toml__ + +```toml +{{#template ../../templates/files/gm/more-chains/gm.toml}} +``` + +> __NOTE__: If you have any `Docker` containers running that might be using the same ports as `gaiad` (e.g. port 27010-27012), please ensure you stop them first before proceeding to the next step. + +Finally, start the chains with the `start` command. + +```bash +{{#template ../../templates/commands/gm/start}} +``` + +This configures and starts four __`gaiad`__ instances. + +```mermaid +graph TD + A[gm] -->|start| C(start chains) + C -->|gaiad| D[ibc-0] + C -->|gaiad| E[ibc-1] + C -->|gaiad| F[ibc-2] + C -->|gaiad| G[ibc-3] + +``` + +If the command runs successfully, it should output something similar to: + +```shell +Creating ibc-0 config... +ibc-0 started, PID: 21330, LOG: $HOME/.gm/ibc-0/log +Creating ibc-1 config... +ibc-1 started, PID: 21888, LOG: $HOME/.gm/ibc-1/log +Creating ibc-2 config... +ibc-2 started, PID: 22443, LOG: $HOME/.gm/ibc-2/log +Creating ibc-3 config... +ibc-3 started, PID: 22999, LOG: $HOME/.gm/ibc-3/log +Creating node-0 config... +node-0 started, PID: 23547, LOG: $HOME/.gm/node-0/log +Creating node-1 config... +node-1 started, PID: 24101, LOG: $HOME/.gm/node-1/log +Creating node-2 config... +node-2 started, PID: 24649, LOG: $HOME/.gm/node-2/log +Creating node-3 config... +node-3 started, PID: 25194, LOG: $HOME/.gm/node-3/log +``` + +Run the following command to check the status of the chains: + +```bash +{{#template ../../templates/commands/gm/status}} +``` + +If the command is successful, you should see a message similar to: +``` +NODE PID RPC APP GRPC HOME_DIR +ibc-0 21330 27010 27011 27012 $HOME/.gm/ibc-0 + node-0 23547 27050 27051 27052 $HOME/.gm/node-0 +ibc-1 21888 27020 27021 27022 $HOME/.gm/ibc-1 + node-1 24101 27060 27061 27062 $HOME/.gm/node-1 +ibc-2 22443 27030 27031 27032 $HOME/.gm/ibc-2 + node-2 24649 27070 27071 27072 $HOME/.gm/node-2 +ibc-3 22999 27040 27041 27042 $HOME/.gm/ibc-3 + node-3 25194 27080 27081 27082 $HOME/.gm/node-3 +``` + + + +### Hermes' configuration file + +Gaiad Manager `gm` takes care of creating the configuration file. Run the command below to create the `$HOME/.hermes/config.toml` file: + +```bash +{{#template ../../templates/commands/gm/hermes_config}} +``` +>__NOTE__: You can visit the [`Configuration`](../../documentation/configuration/index.md) section for more information about the configuration file. + +Based on the `gm.toml` above, your `$HOME/.hermes/config.toml` file should look like: + +__config.toml__ + +```toml +{{#template ../../templates/files/hermes/more-chains/config_without_filters.toml}} +``` + +### Adding private keys to the chains + +Next, we will need to associate a private key to every chain which `hermes` will use to sign transactions. `gm` will automatically generate and associate them with: + +```bash +{{#template ../../templates/commands/gm/hermes_keys}} +``` + +If successful, the command should show an output similar to: + +``` +SUCCESS Added key 'wallet' (cosmos1qsl5sq48r7xdfwq085x9pnlfu9ul5seufu3n03) on chain ibc-0 +SUCCESS Added key 'wallet2' (cosmos1haaphqucg2u9g8gwgv6z8jzegvca85r4d7yqh9) on chain ibc-0 +SUCCESS Added key 'wallet1' (cosmos1cgjf7m9txsxf2pdekxk60ll6xusx0heznqsnxn) on chain ibc-0 +SUCCESS Added key 'wallet' (cosmos1zp3t2rp7tjr23wchp36lmw7vhk77gtvvc7lc5s) on chain ibc-1 +SUCCESS Added key 'wallet2' (cosmos1644x9c8pyfwcmg43ch2u3vr6hl4rkmkz2weq39) on chain ibc-1 +SUCCESS Added key 'wallet1' (cosmos1dsrj2uqjvtssenkwperuvfkgkg2xvmydvpzswy) on chain ibc-1 +SUCCESS Added key 'wallet' (cosmos1k6c6le34zsmz34yez84a7tquedy3mkc3hy7wg8) on chain ibc-2 +SUCCESS Added key 'wallet2' (cosmos1murv55h3utv5ck0a2tk5ue3n88wgglhlhyzyq8) on chain ibc-2 +SUCCESS Added key 'wallet1' (cosmos1r8sq88n4k8ajsmq3sscnsd8829lqxvsmue2gf7) on chain ibc-2 +SUCCESS Added key 'wallet' (cosmos1eykzqwq20sqdgvhf0tmz6xjq9mlcluwxed77gj) on chain ibc-3 +SUCCESS Added key 'wallet2' (cosmos1lz6df9uggl9459z2vusw9tknpy3xn2v7yq60k9) on chain ibc-3 +SUCCESS Added key 'wallet1' (cosmos15jxyjskrx7s8yqpfn3xddlrx7qcq0f8r69mp4g) on chain ibc-3 +``` + +> __TROUBLESHOOTING__: +> - If the command does not out output anything, make sure the path to Hermes' binary is set in `{{#template ../../templates/path/gm/default_path}}`. + +### The `$HOME/.gm` directory + +This directory is created when you install `gm` and the binaries are stored here but when we start the chains, all the related files and folders are stored here as well. + +The `$HOME/.gm` directory has a tree structure similar to: + +```shell +.gm +├── bin +│   ├── gm +│   ├── lib-gm +│   └── shell-support +├── gm.toml +├── ibc-0 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── keyring-test +│   ├── log +│   ├── pid +│   ├── validator_seed.json +│   ├── wallet1_seed.json +│   ├── wallet2_seed.json +│   └── wallet_seed.json +├── ibc-1 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── keyring-test +│   ├── log +│   ├── pid +│   ├── validator_seed.json +│   ├── wallet1_seed.json +│   ├── wallet2_seed.json +│   └── wallet_seed.json +├── ibc-2 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── keyring-test +│   ├── log +│   ├── pid +│   ├── validator_seed.json +│   ├── wallet1_seed.json +│   ├── wallet2_seed.json +│   └── wallet_seed.json +├── ibc-3 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── keyring-test +│   ├── log +│   ├── pid +│   ├── validator_seed.json +│   ├── wallet1_seed.json +│   ├── wallet2_seed.json +│   └── wallet_seed.json +├── node-0 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── log +│   └── pid +├── node-1 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── log +│   └── pid +├── node-2 +│   ├── config +│   ├── data +│   ├── init.json +│   ├── log +│   └── pid +└── node-3 + ├── config + ├── data + ├── init.json + ├── log + └── pid + +``` + +> __Tip__: You can use the command `tree ./data/ -L 2` to view the folder structure above + +### The `$HOME/.hermes` directory + +By default, `hermes` expects the configuration file to be in the __`$HOME/.hermes`__ folder. + +It also stores the private keys for each chain in this folder as outlined in the [Keys](../../commands/keys/index.md) section. + +After executing `{{#template ../../templates/commands/gm/start}}`, this is how the folder should look like: + +```shell +$HOME/.hermes/ +├── config.toml +└── keys + ├── ibc-0 + │   └── keyring-test + │   ├── wallet.json + │   ├── wallet1.json + │   └── wallet2.json + ├── ibc-1 + │   └── keyring-test + │   ├── wallet.json + │   ├── wallet1.json + │   └── wallet2.json + ├── ibc-2 + │   └── keyring-test + │   ├── wallet.json + │   ├── wallet1.json + │   └── wallet2.json + └── ibc-3 + └── keyring-test + ├── wallet.json + ├── wallet1.json + └── wallet2.json +``` + +--- + +## Next Steps + +[The next section](./build-the-topology.md) describes how to create an arbitrary topology between these chains before relaying packets. diff --git a/guide/src/tutorials/more-chains/start-relaying.md b/guide/src/tutorials/more-chains/start-relaying.md new file mode 100644 index 0000000000..439aad52c5 --- /dev/null +++ b/guide/src/tutorials/more-chains/start-relaying.md @@ -0,0 +1,358 @@ +# Start relaying + +In the previous tutorial, you learned about how to relay packets between a pair of chains on a relay path. Now, you will learn how to relay packets on an arbitrary topology. + +>__WARNING__ Before proceeding to the sections below, please first, make sure you followed the steps in the [Build the topology section](./build-the-topology.md). + +The chains should be fully connected and the relayer should be setup to relay on these channels: + +```mermaid +flowchart TD +ibc0((ibc-0)) +ibc0ibc1[[channel-0]] +ibc0ibc3[[channel-2]] + +ibc1((ibc-1)) +ibc1ibc0[[channel-0]] +ibc1ibc2[[channel-1]] + +ibc2((ibc-2)) +ibc2ibc1[[channel-1]] +ibc2ibc3[[channel-2]] + +ibc3((ibc-3)) +ibc3ibc0[[channel-0]] +ibc3ibc2[[channel-2]] + +ibc0---ibc0ibc1---ibc1ibc0---ibc1 +ibc0---ibc0ibc3---ibc3ibc0---ibc3 +ibc1---ibc1ibc2---ibc2ibc1---ibc2 +ibc2---ibc2ibc3---ibc3ibc2---ibc3 +``` + +--- + +## Query balances + +- Balances on `ibc-0`: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27050 home=~/.gm/ibc-0 wallet=wallet}} + ``` + +- Balances on `ibc-1`: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27060 home=~/.gm/ibc-1 wallet=wallet}} + ``` + +- Balances on `ibc-2`: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27070 home=~/.gm/ibc-2 wallet=wallet}} + ``` + +- Balances on `ibc-3`: + + ```shell + {{#template ../../templates/commands/gaia/query_balances node=tcp://localhost:27080 home=~/.gm/ibc-3 wallet=wallet}} + ``` + +> __NOTE__ the RPC addresses used in the two commands above are configured in `~/.hermes/config.toml` file. It can also be found with `{{#template ../../templates/commands/gm/status}}` + +At this point in the tutorial, every command should output something similar to: + +``` +balances: +- amount: "100000000" + denom: samoleans +- amount: "99982481" + denom: stake +pagination: + next_key: null + total: "0" +``` + +## Start relaying + +Now, let's exchange `samoleans` between chains. + +- Open a new terminal and start Hermes using the `start` command : + + ```shell + {{#template ../../templates/commands/hermes/start}} + ``` + Hermes will first relay the pending packets that have not been relayed and then start passively relaying by listening for and acting on packet events. + +- Let's transfer `1000000 samoleans` from ibc-1 to ibc-3. There is a direct path between ibc-1 (channel-2) and ibc-3 (channel-1). Let's attempt the transfer on this path. + + - In a separate terminal, use the `ft-transfer` command to send `1000000 samoleans` from ibc-1 to ibc-3 from channel-2: + ```shell + {{#template ../../templates/commands/hermes/transfer dst-chain=ibc-3 src-chain=ibc-1 src-port=transfer src-channel=channel-2 amount=1000000 timeout-seconds=10000}} + ``` + - Wait a few seconds then query balances on `ibc-1` and `ibc-3`. You should observe that `ibc-1` lost 1000000 samoleans but `ibc-3` did not receive any: + + * Balances at ibc-1 : + ``` + balances: + - amount: "99000000" + denom: samoleans + - amount: "99980646" + denom: stake + pagination: + next_key: null + total: "0" + ``` + * Balances at ibc-3 : + ``` + balances: + - amount: "100000000" + denom: samoleans + - amount: "99979803" + denom: stake + pagination: + next_key: null + total: "0" + ``` + + - Observe the output on the relayer terminal and verify that no event is processed. + + If you correctly created the packet filters in the [previous section](./build-the-topology.md), the relayer does not relay on this path. So what happened to the 1000000 samoleans you just sent ? It is stuck until a relayer decides to relay this packet to `ibc-3`. For now, let's forget about these samoleans. We can get as many as we want anyway. + + It might be impossible to send packets directly from `ibc-1` to `ibc-3`, however, it is possible to use `ibc-2` as a bridge: + + ```mermaid + graph LR; + A((ibc-1)) --> B((ibc-2)) --> C((ibc-3)) + ``` + +- In a separate terminal, use the `ft-transfer` command to send `1000000 samoleans` from ibc-1 to ibc-2 from channel-1: + ```shell + {{#template ../../templates/commands/hermes/transfer dst-chain=ibc-2 src-chain=ibc-1 src-port=transfer src-channel=channel-1 amount=1000000 timeout-seconds=10000}} + ``` +- Wait a few seconds then query balances on `ibc-1` and `ibc-2`. You should observe something similar to: + - Balances on `ibc-1`: + ``` + balances: + - amount: "98000000" + denom: samoleans + - amount: "99979707" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances at ibc-2: + ``` + balances: + - amount: "1000000" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99979154" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The samoleans were transferred to `ibc-1` and are visible under the denomination `ibc/C1840...` (it might be a different one for you). + +- Transfer these tokens to `ibc-3`: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-3 src-chain=ibc-2 src-port=transfer src-channel=channel-2 amount=1000000 timeout-seconds=10000 denom=ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199}} + ``` +- Wait a few seconds then query balances on `ibc-2` and `ibc-3`. You should observe something similar to: + - Balances on `ibc-2`: + ``` + balances: + - amount: "0" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99977059" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances on `ibc-3`: + ``` + balances: + - amount: "1000000" + denom: ibc/C658F0EB9DE176E080B586D634004141239C3E55676462C976266DB54C56EBE4 + - amount: "100000000" + denom: samoleans + - amount: "99978251" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The tokens were correctly received by `ibc-3` under the denomination `ibc/C658...`. + +## Send back the tokens + +Now let's send some of these coins back to `ibc-1`. We will dedicate half of them to learn a valuable lesson while the other half will be correctly transferred back. + +### The wrong way + +Let's start with a common mistake and send back these coins on a different path than the one they were received on: + +__Another path to ibc-1__ + +```mermaid +graph LR; +A((ibc-3)) --> B((ibc-0)) --> C((ibc-1)); +``` + +- Use the `ft-transfer` command to transfer `500000 ibc/C658...` tokens from `ibc-3` to `ibc-0`: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-0 src-chain=ibc-3 src-port=transfer src-channel=channel-0 amount=500000 timeout-seconds=10000 denom=ibc/C658F0EB9DE176E080B586D634004141239C3E55676462C976266DB54C56EBE4}} + ``` +- Wait a few seconds, then query balances on `ibc-0` and `ibc-3`. You should observe something similar to: + - Balances on `ibc-0`: + ``` + balances: + - amount: "500000" + denom: ibc/563FDAE5A0D8C15013E4485134A2D2EE3317452278B56B2ED63DDB4EB677DF84 + - amount: "100000000" + denom: samoleans + - amount: "99980928" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances on `ibc-3`: + ``` + balances: + - amount: "500000" + denom: ibc/C658F0EB9DE176E080B586D634004141239C3E55676462C976266DB54C56EBE4 + - amount: "100000000" + denom: samoleans + - amount: "99976153" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The tokens were correctly received by `ibc-0` under the denomination `ibc/563...`. + +- Transfer the `ibc/563...` tokens from `ibc-0` to `ibc-1`: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-1 src-chain=ibc-0 src-port=transfer src-channel=channel-0 amount=500000 timeout-seconds=10000 denom=ibc/563FDAE5A0D8C15013E4485134A2D2EE3317452278B56B2ED63DDB4EB677DF84}} + ``` + +- Wait a few seconds then query balances on `ibc-0` and `ibc-3`. You should observe something similar to: + - Balances on `ibc-0`: + ``` + balances: + - amount: "0" + denom: ibc/563FDAE5A0D8C15013E4485134A2D2EE3317452278B56B2ED63DDB4EB677DF84 + - amount: "100000000" + denom: samoleans + - amount: "99978828" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances on `ibc-1`: + ``` + balances: + - amount: "500000" + denom: ibc/8F3641F853A1D075C549E733AB624BA8607C8D2FFC26B32717DE660AE6A34A73 + - amount: "98000000" + denom: samoleans + - amount: "99978141" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The tokens were successfully received by `ibc-1` under the denomination `ibc/8F3...` while they should be recognized as samoleans. Indeed, **it is impossible to transfer back tokens from a different channel than the one they were received from**. + + Let's forget about these tokens. + +### The right way + +Now that you have seen the wrong way to transfer back tokens, let's see the right way. **Tokens should be transferred back on the same path they were received**. + +__Correct Path__: +```mermaid +graph LR; +A((ibc-3))-->B((ibc-2))-->C((ibc-1)); +``` + +- Use the `ft-transfer` command to transfer `500000 ibc/C658...` tokens from `ibc-3` to `ibc-2`: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-2 src-chain=ibc-3 src-port=transfer src-channel=channel-2 amount=500000 timeout-seconds=10000 denom=ibc/C658F0EB9DE176E080B586D634004141239C3E55676462C976266DB54C56EBE4}} + ``` +- Wait a few seconds then query balances on `ibc-2` and `ibc-3`. You should observe something similar to: + - Balances at ibc-2: + ``` + balances: + - amount: "500000" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99975713" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances at ibc-3: + ``` + balances: + - amount: "0" + denom: ibc/C658F0EB9DE176E080B586D634004141239C3E55676462C976266DB54C56EBE4 + - amount: "100000000" + denom: samoleans + - amount: "99973935" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The tokens were correctly received by `ibc-0` under the denomination `ibc/C184...`. The tokens retrieved the denomination they had before they were transferred to ibc-3. + +- Transfer the `ibc/C184...` tokens from ibc-2 to ibc-1: + ```shell + {{#template ../../templates/commands/hermes/transfer_with_denom dst-chain=ibc-1 src-chain=ibc-2 src-port=transfer src-channel=channel-1 amount=500000 timeout-seconds=10000 denom=ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199}} + ``` + +- Wait a few seconds, then query balances on `ibc-1` and `ibc-2`. You should observe something similar to: + - Balances on `ibc-1`: + ``` + balances: + - amount: "500000" + denom: ibc/8F3641F853A1D075C549E733AB624BA8607C8D2FFC26B32717DE660AE6A34A73 + - amount: "98500000" + denom: samoleans + - amount: "99975741" + denom: stake + pagination: + next_key: null + total: "0" + ``` + - Balances on `ibc-2`: + ``` + balances: + - amount: "0" + denom: ibc/C1840BD16FCFA8F421DAA0DAAB08B9C323FC7685D0D7951DC37B3F9ECB08A199 + - amount: "100000000" + denom: samoleans + - amount: "99974602" + denom: stake + pagination: + next_key: null + total: "0" + ``` + The tokens were successfully received by `ibc-1` under the denomination `samoleans`. + +--- + +## Next Steps + +In the [next section](./concurrent-instances.md), you will start new instances of Hermes to relay packets over the channels that were filtered out by the first instance. diff --git a/guide/src/tutorials/pre-requisites/gaia.md b/guide/src/tutorials/pre-requisites/gaia.md new file mode 100644 index 0000000000..506b224f57 --- /dev/null +++ b/guide/src/tutorials/pre-requisites/gaia.md @@ -0,0 +1,52 @@ +# Install Gaia + +For `gm` to start the chains, it requires `Gaia` to be installed. + +> __NOTE__: This assumes you have `Golang` programming language installed on +> your machine. If not, please ensure you install before proceeding. See +> more details in the [Pre-requisites](../../quick-start/pre-requisites.md#2-golang) section. + +Follow the instructions below to install `Gaia`. + +--- + +#### Clone Gaia + +Clone the repository from GitHub: + +```shell +{{#template ../../templates/commands/git/gaia}} ~/go/src/github.com/cosmos/gaia +``` + +#### Build and Install + +Run the `make` command to build and install `gaiad` + +```shell +cd ~/go/src/github.com/cosmos/gaia +git checkout v4.2.1 +make install +``` + +>__NOTE__: Specific to M1 macOS, there could be some warnings after running `make install` which can be safely ignored as long as `gaiad` binaries are built in `$HOME/go/bin` directory. +>

Add the path `export PATH=$HOME/go/bin:$PATH` + +If the command is successful, you can run the following command to ensure it was properly installed: + +```shell +{{#template ../../templates/commands/gaia/version}} +``` + +Output: +```shell +name: gaia +server_name: gaiad +version: v4.2.1 +commit: dbd8a6fb522c571debf958837f9113c56d418f6b +``` + +--- + +## Next Steps + +Go to the [next section](./gaiad-manager.md) to install `gm`, a tool to easily start IBC-enabled local chains. \ No newline at end of file diff --git a/guide/src/tutorials/pre-requisites/gaiad-manager.md b/guide/src/tutorials/pre-requisites/gaiad-manager.md new file mode 100644 index 0000000000..7c188c8a4f --- /dev/null +++ b/guide/src/tutorials/pre-requisites/gaiad-manager.md @@ -0,0 +1,90 @@ +## Install Gaiad Manager + +Gaiad manager (`gm`) is a command-line tool (CLI) that helps manage local `gaiad` networks. + +Follow the instructions below to install and configure `gm`. + +--- + +### Requirements +* Bourne shell (`sh`) +* [`sconfig`](https://github.com/freshautomations/sconfig/releases) and + [`stoml`](https://github.com/freshautomations/stoml/releases) installed in your PATH (put them in `/usr/local/bin`) +* `sed`, `tr` +* For shell-completion Bourne Again Shell (`bash`) for the local user + +### How to run + +1. Install the dependencies. + + On macOS: + ```bash + # You might need sudo permissions and create the `usr/local/bin` directory + + curl -Lo /usr/local/bin/sconfig https://github.com/freshautomations/sconfig/releases/download/v0.1.0/sconfig_darwin_amd64 + curl -Lo /usr/local/bin/stoml https://github.com/freshautomations/stoml/releases/download/v0.7.0/stoml_darwin_amd64 + chmod 755 /usr/local/bin/sconfig + chmod 755 /usr/local/bin/stoml + ``` + On Linux: + ```bash + curl -Lo /usr/local/bin/sconfig https://github.com/freshautomations/sconfig/releases/download/v0.1.0/sconfig_linux_amd64 + curl -Lo /usr/local/bin/stoml https://github.com/freshautomations/stoml/releases/download/v0.7.0/stoml_linux_amd64 + chmod 755 /usr/local/bin/sconfig + chmod 755 /usr/local/bin/stoml + ``` + +2. Install `gm` + + ```bash + {{#template ../../templates/commands/git/clone_ibc_rs}} + ibc-rs/scripts/gm/bin/gm install + ``` + Alternatively, you can create the folder `$HOME/.gm/bin` and copy the files from `scripts/gm/bin` in there. + +3. Activate `gm` +* Add `source $HOME/.gm/bin/shell-support` to a file that executes when a new terminal window comes up + (`$HOME/.bash_profile` or `$HOME/.bashrc` or `$HOME/.zprofile`) +* (Optional) Enable auto-completion + + - On macOS: + + ```bash + # Note: zsh is the default shell on MacOS, so no need to run this unless you explicitly use bash + brew install bash-completion + ``` + + - On Linux: + + ``` + apt install bash-completion || yum install bash-completion + ``` + +* Restart your terminal + +Note: The `shell-support` script allows bash-completion as well as creating a `gm` alias, so you don't need to add more +entries to your PATH environment variable. If you don't want to use this, you can always just add `$HOME/.gm/bin` to +your path. + +### The configuration: `gm.toml` +**Where**: `{{#template ../../templates/path/gm/default_path}}`. + +**Description**: This file contains all the high-level node configuration that `gm` is aware of. Note that all entries under `[global]` are also valid entries under any `[node]` header, and can be used to override the global entries for specific nodes/validators. + +**Entries**: All entries are defined and documented in the `scripts/gm/gm.toml` example configuration file. + +Copy and paste below to `{{#template ../../templates/path/gm/default_path}}` and set Hermes' binary path according to your setup. + +The following configuration you need to specify 2 `gaiad` chains. `hermes` will know about these chains. + +```toml +{{#template ../../templates/files/gm/default_gm.toml}} +``` + +> __NOTE:__ Go to this page for more details about [Gaiad Manager](https://github.com/informalsystems/ibc-rs/tree/master/scripts/gm) + +--- + +## Next steps + +Now that `Gaiad Manager` is installed on your machine, visit the [first tutorial](../local-chains/index.md) to learn the basics of Hermes. You will start two local chains and exchange tokens over IBC transfers. diff --git a/guide/src/tutorials/pre-requisites/index.md b/guide/src/tutorials/pre-requisites/index.md new file mode 100644 index 0000000000..2591b28947 --- /dev/null +++ b/guide/src/tutorials/pre-requisites/index.md @@ -0,0 +1,13 @@ +# Pre-requisites for local chains + +In order to follow the tutorials using local chains, please make sure that [Gaia](https://github.com/cosmos/gaia) and [Gaiad manager](./gaiad-manager.md) are installed on your machine. + +--- + +## Sections + +* **[Gaia](./gaia.md)** + * Install `Gaia`, the first implementation of the CosmosHub. + +* **[Gaiad Manager](./gaia.md)** + * Install Gaiad Manager, a command-line tool (CLI) that helps manage local `gaiad` networks. \ No newline at end of file diff --git a/guide/src/tutorials/production/index.md b/guide/src/tutorials/production/index.md new file mode 100644 index 0000000000..e9d2dc7991 --- /dev/null +++ b/guide/src/tutorials/production/index.md @@ -0,0 +1,20 @@ +# Production + +In this tutorial, you will learn how to set up Hermes to relay between the Cosmos Hub chain and the Osmosis chain. + +You will monitor the relayer's activity with a [`Grafana dashboard`](https://grafana.com/) from which it is possible to visualize both the logs and the metrics produced by Hermes. + +The [next section](./setup-grafana.md) will contain the steps to install all the dependencies of the monitoring platform. + +--- + +## Sections + +* **[Set up Grafana](./setup-grafana.md)** + * Learn how to set up [Grafana](https://grafana.com)'s monitoring stack for Hermes. + +* **[Set up Hermes](./setup-hermes.md)** + * Learn how to configure Hermes on production chains (Cosmos Hub <> Osmosis). + +* **[Start relaying](./start-relaying.md)** + * Exchange and relay packets between production chains. diff --git a/guide/src/tutorials/production/setup-grafana.md b/guide/src/tutorials/production/setup-grafana.md new file mode 100644 index 0000000000..348aa65b73 --- /dev/null +++ b/guide/src/tutorials/production/setup-grafana.md @@ -0,0 +1,77 @@ +# Setup Grafana + +Hermes provides many metrics to monitor its activity. You can find a detailed description of all the metrics in the [Telemetry](../../documentation/telemetry/index.md) section. In this chapter, you will install [Grafana](https://grafana.com/) components which will ingest the data produced by Hermes and provide both analytics and visualization. + +--- +## Install Docker + +You will need [Docker](https://www.docker.com/) installed and configured on your machine. We provide a [Compose file](../../assets/docker-compose.yaml) to install Grafana and all its dependencies through Docker. + +To install and configure Docker, please follow the [Docker official documentation](https://docs.docker.com/get-docker/). + +## Tools + +### Grafana Dashboard +[Grafana](https://grafana.com/) is a multi-platform open source analytics and interactive visualization web application. It provides charts, graphs, and alerts for the web when connected to supported data sources. It can be used to monitor the health of an application and the data it produces. In the following tutorial, we will use a Grafana Dashboard to visualize the [Prometheus](https://prometheus.io/) metrics and the logs. + +### Prometheus + +Prometheus is a free software application used for event monitoring and alerting. It records real-time metrics in a time series database (allowing for high dimensionality) built using an HTTP pull model, with flexible queries and real-time alerting. Hermes can expose Prometheus metrics. The Prometheus server will pull them and Grafana will use this server as a data source for data visualization. + +### Grafana Loki + +[Loki](https://grafana.com/oss/loki/) is a horizontally scalable, highly available, multi-tenant log aggregation system inspired by Prometheus. It will be used to aggregate the logs produced by Hermes. + +### Promtail + +[Promtail](https://grafana.com/docs/loki/latest/clients/promtail/) is an agent which ships the contents of local logs to a private Grafana Loki instance or Grafana Cloud. It is usually deployed to every machine that has applications needed to be monitored. You will use it to ship Hermes' logs to Loki. + +>__NOTE__: You will redirect `hermes`' output to `/var/log/hermes.log`. The configuration we provide ships every log file in `/var/log` to Loki. + +## Setup Grafana + +### Installation +- Download [docker-compose.yaml](../../assets/docker-compose.yaml), [prometheus.yaml](../../assets/docker-compose.yaml) and [grafana_template.json](../../assets/grafana_template.json) and place them in the same repository. + +- Run the following command in your command line to start Grafana, Prometheus, Loki, and Promtail. + ``` + docker-compose -f docker-compose.yaml up + ``` + +### Sign in to Grafana + +- Open your web browser and go to `http://localhost:3000/`. +- On the sign-in page, enter `admin` for the username and password. +- Click Sign in. + If successful, you will see a prompt to change the password. +- Click OK on the prompt and change your password. + +### Add Prometheus + +- In the sidebar, hover your cursor over the Configuration (gear) icon, and then select `Data Sources`. +- Click `Add data source`. +- In the list of data sources, select `Prometheus`. +- In the URL box, enter `http://prometheus:9090`. +- Click `Save & Test`. + Prometheus is now available as a data source in Grafana. + +### Add Loki + +- Add another data source, however, this time, select `Loki`. +- In the URL box, enter `http://loki:3100`. +- Click `Save & Test`. + Loki is now available as a data source in Grafana. + +### Set up the dashboard + +- Download the [Grafana template](../../assets/grafana_template.json) we provide. +- In the sidebar, hover your cursor over the Dashboard icon, and then click `Import`. +- Click on `Upload JSON file` and select the Grafana template you just downloaded. +- On the `Import` page, enter `Hermes dashboard template` as a name, enter your data sources and click `Import`. +- In the top right corner, next to the `refresh dashboard` button, select `5s` to automatically query Prometheus and Loki every 5s. + +--- + +## Next steps + +In the [next section](./setup-hermes.md), you will learn how to set up Hermes on production chains. diff --git a/guide/src/tutorials/production/setup-hermes.md b/guide/src/tutorials/production/setup-hermes.md new file mode 100644 index 0000000000..7492f29d6d --- /dev/null +++ b/guide/src/tutorials/production/setup-hermes.md @@ -0,0 +1,108 @@ +# Setup Hermes + +In this section, you will learn how to set up Hermes to relay between the Hub and Osmosis. You will relay on channels that are already created. **It is strongly advised not to create any channels between two chains if another one with the same port already exists.** + +--- + +## Setup accounts + +First, you need a wallet with enough funds on both chains. This tutorial assumes that you already have wallets created on the chains you want to relay on, and that these wallets have funds allocated to each of them. + +### Adding a private key + +You can add a private key using one of two different ways: + +- If you have a [key-seed file](../../documentation/commands/keys/index.md#key-seed-file-private-key), use the commands : + ```shell + {{#template ../../templates/commands/hermes/keys_add_key_file chain=cosmoshub-4 key-file=key_file_hub.json}} + {{#template ../../templates/commands/hermes/keys_add_key_file chain=osmosis-1 key-file=key_file_osmosis.json}} + ``` +>__NOTE__: Do not confuse the `chain-name` and the `chain-id` which follows the format `chain_name-version`. + +- If you have a `mnemonic`, you can restore a private key from a [mnemonic-file](../../documentation/commands/keys/index.md#restore-a-private-key-to-a-chain-from-a-mnemonic). The following steps create a `mnemonic-file` and restore its key for each chain under names `keyhub` and `keyosmosis` : + ```shell + echo word1 ... word12or24 > mnemonic_file_hub + {{#template ../../templates/commands/hermes/keys_add_mnemonic chain=cosmoshub-4 mnemonic-file=mnemonic_file_hub.json key-name=keyhub}} + rm mnemonic_file_hub + echo word1 ... word12or24 > mnemonic_file_osmosis + {{#template ../../templates/commands/hermes/keys_add_mnemonic chain=osmosis-1 mnemonic-file=mnemonic_file_osmosis.json key-name=keyosmosis}} + rm mnemonic_file_osmosis + ``` + +## Configuration file + +Then, you need to create a configuration file for Hermes (more details in the [documentation](../../documentation/configuration/index.md)). + +The command `hermes config auto` provides a way to automatically generate a configuration file for chains in the [chain-registry](https://github.com/cosmos/chain-registry): + +```shell +{{#template ../../templates/commands/hermes/config_auto output=$HOME/.hermes/config.toml chains=cosmoshub:keyhub osmosis:keyosmosis}} +``` +>__NOTE__: This command also automatically finds IBC paths and generates packet filters from the [_IBC](https://github.com/cosmos/chain-registry/tree/master/_IBC) folder in the chain-registry. + +If the command runs successfully, it should output: +``` +2022-08-26T11:40:35.164371Z INFO ThreadId(01) using default configuration from '$HOME/.hermes/config.toml' +2022-08-26T11:40:35.165353Z INFO ThreadId(01) Fetching configuration for chains: ["cosmoshub", "osmosis"] +2022-08-26T11:40:36.253328Z WARN ThreadId(01) cosmoshub-4: uses key "keyhub" +2022-08-26T11:40:36.253704Z WARN ThreadId(01) osmosis-1: uses key "keyosmosis" +2022-08-26T11:40:36.253860Z WARN ThreadId(01) Gas parameters are set to default values. +SUCCESS "Config file written successfully : $HOME/.hermes/config.toml." +``` +And generate the following configuration : + +__config.toml__ +```toml +{{#template ../../templates/files/hermes/production/config.toml}} +``` +>__NOTE__: You might not have the same RPC and gRPC endpoints in your configuration file as they are randomly selected in the chain-registry. + +The command created packet filters so the relayer will only relay on `channel-0` for `osmosis-1` and `channel-141` for `cosmoshub-4`. It uses RPC and gRPC endpoints found in the chain registry. If you also run a full node, you can replace the endpoints with your own. It has many advantages as you can accept transactions with lower gas. + +>__WARNING__: It is difficult to estimate how much gas you will spend as it depends on many parameters like: +> - The volume of transactions. More congestion means higher gas prices. +> - The transaction's size. Bigger transactions need more gas. +> - The volume of IBC messages to relay. +> +> We cannot provide a way to precisely set those parameters. However, you can refer to [other operators' configuration](https://github.com/informalsystems/ibc-rs/discussions/2472#discussioncomment-3331695). You can also find IBC transfers on [mintscan.io](https://www.mintscan.io/cosmos/txs) to observe how much other operators are spending. But remember that if the gas wanted is too low, the transactions will fail. If the gas price is too high gas will be wasted, but the transactions will have a higher priority. + +For the tutorial, we will follow the [example of Crypto Crew](https://github.com/notional-labs/notional/blob/master/relaying/hermes/all-ibc.toml) and set the gas parameters as follows. + +- For Cosmoshub: +```toml +{{#template ../../templates/files/hermes/production/default_gas_cosmoshub}} +``` + +- For Osmosis: +```toml +{{#template ../../templates/files/hermes/production/default_gas_osmosis}} +``` + +>__NOTE__: `max_msg_nums` defines the number of messages that can be sent in the same transaction. + +>__DISCLAIMER__: These parameters need to be tuned. We can not guarantee that they will always work and kept up to date. + +## Health-check + +Finally, perform a `health-check` to verify that your setup is correct with: +```shell +{{#template ../../templates/commands/hermes/health_check}} +``` + +If the command runs successfully, it should output: +``` +2022-08-26T15:54:21.321683Z INFO ThreadId(01) using default configuration from '$HOME/.hermes/config.toml' +2022-08-26T15:54:21.321882Z INFO ThreadId(01) [cosmoshub-4] performing health check... +2022-08-26T15:54:22.909339Z WARN ThreadId(01) chain is healthy chain=cosmoshub-4 +2022-08-26T15:54:22.909374Z INFO ThreadId(01) [osmosis-1] performing health check... +2022-08-26T15:54:23.954362Z INFO ThreadId(01) chain is healthy chain=osmosis-1 +SUCCESS performed health check for all chains in the config +``` + +>__WARNING__: In the previous tutorials, after setting up Hermes, we started by creating a new relay path. In production, the relay path most likely already exists and does not need to be created. **Do not create channels between the Hub and Osmosis.** + +--- + +## Next steps + +You are now ready to relay. In the [next chapter](./start-relaying.md), you will start relaying and monitoring Hermes with Grafana. diff --git a/guide/src/tutorials/production/start-relaying.md b/guide/src/tutorials/production/start-relaying.md new file mode 100644 index 0000000000..b5d43cf984 --- /dev/null +++ b/guide/src/tutorials/production/start-relaying.md @@ -0,0 +1,40 @@ +# Start relaying + +In section [Setup Grafana](./setup-grafana.md), you did set up a Grafana dashboard which is now waiting to receive data produced by `hermes` and running on port 3000. You also configured Hermes in section [Setup Hermes](./setup-hermes.md) and added the keys you will be using. + +--- + +## Create an empty log file + +Promtail is shipping every log file from `/var/log` to Loki. Follow the steps below to create an empty log file for Hermes: +```shell +sudo touch /var/log/hermes.log +sudo chown $(whoami) /var/log/hermes.log +``` +You should now have an empty `hermes.log` file that you can access and see on the Grafana Dashboard, on the `explore` page, if you select Loki as a data source. You can query the label `filename=hermes.log`. + +## Start relaying + +Follow the steps to get started : + +- Open your dashboard. Make sure it gets refreshed every 5s. + +- In a new terminal, run `{{#template ../../templates/commands/hermes/start}} &> hermes.log`. + +If the command runs successfully, you should be able to see the metrics panels displaying data on the Grafana Dashboard and you should also be able to see the logs on the `Logs` panel at the top of the dashboard. You can also explore them on the `explore` page. + +You can now inspect the logs to verify whether the gas parameters are set correctly and tune them as possible. However, remember to restart Hermes when you modify the configuration. + +Finally, Hermes is designed to relay without any intervention, however, you might have to manually trigger `hermes clear packets` to clear outstanding packets that Hermes failed to relay. + +>__NOTE__: It is not possible to share a wallet between two instances of Hermes. + +--- + +## Next steps + +Visit the [Telemetry](../../documentation/telemetry/index.md) section to learn how to use the metrics and the [Avanced](../../advanced/index.md) section to learn about Hermes' features and general guidelines for troubleshooting. + +You can also learn more about [Grafana's features](https://grafana.com/tutorials/grafana-fundamentals/) and learn how to create a [Grafana Managed Alert](https://grafana.com/docs/grafana/latest/alerting/alerting-rules/create-grafana-managed-rule/). + +>__NOTE__: In the future, Hermes might implement functionalities to trigger the commands through a REST API. It might become possible to manipulate the relayer through Grafana Alerts.