diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index f54c6d02..26e8419d 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -13,13 +13,13 @@ Relayers are a crucial piece of infrastructure that allow IBC compatible chains A relayer is responsible for posting IBC packets to the destination chain, as well as performing other IBC functions such as creating channels, updating the light client states and checking for misbehavior. -Operating a relayer is permissionless. If at least one relayer is not running on a given channel between two chains, -they will not be able to pass messages to each other on that channel. IBC transfers that are attempted but not picked +Operating a relayer is permissionless. There must be at least one relayer running on a given channel between two chains if the chains are +to pass messages to each other on that channel. IBC transfers that are attempted but not picked up by a relayer will timeout and the tokens will be refunded to the sender. To operate a relayer, you will need: - A dedicated server -- [Hermes](#install-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. +- [Hermes](#installing-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. - Full nodes on both chains; a relayer needs to access several weeks worth of chain history and to frequently post transactions to both chains. For testing, a public RPC node may suffice, but for production it is highly recommended for reliability that relayer operators also operate both full nodes themselves. @@ -29,14 +29,14 @@ wallet on each with enough funds to cover gas costs (monitoring and topping up a This document covers the essentials for installing, configuring and running a relayer on Namada: -1. [Installing Hermes](#install-hermes) -2. [Configuring Hermes](#configure-hermes) +1. [Installing Hermes](#installing-hermes) +2. [Configuring Hermes](#configuring-hermes) 3. [Setting up the relayer](#setting-up-the-relayer) 4. [Creating an IBC channel](#creating-an-ibc-channel) -5. [Running the relayer](#start-the-relayer) +5. [Running the relayer](#running-the-relayer) And for setting up a testing environment by running two local Namada chains, see the section -[Testing with local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) +[Testing with local Namada chains](#testing-with-local-namada-chains) ### Installing Hermes @@ -88,7 +88,7 @@ sudo cp ./target/release/hermes /usr/local/bin/ ### Configuring Hermes #### Make Hermes config file -Hermes' `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: +The Hermes `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: ```bash copy export HERMES_CONFIG="$HOME/.hermes/config.toml" @@ -210,7 +210,7 @@ These are the pieces of this puzzle you want to keep your 👀 on: - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. - `trusting_period` specifies the maximum period before which the client can not expire. This should be not more than unbonding time in the particular chain. -You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). +You can see more details of configuration in [the official Hermes documentation](https://hermes.informal.systems/documentation/configuration). #### Export environment variables @@ -295,18 +295,6 @@ Note that the above `CHAIN_IDs` will depend on your own setup, so do check this When the creation has been completed, you can see the channel IDs. For example, the output text below shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. -Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID -for a transfer from Chain A to Chain B. Also, you specify -`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) - -Also note the ClientId for each of the chains; we will need them on the next step: -`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` - -```bash copy -export CLIENT_A_ID="" -export CLIENT_B_ID="" -``` - ``` SUCCESS Channel { @@ -364,6 +352,18 @@ SUCCESS Channel { ``` +Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID +for a transfer from Chain A to Chain B. Also, you specify +`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) + +Also note the ClientId for each of the chains; we will need them on the next step: +`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` + +```bash copy +export CLIENT_A_ID="" +export CLIENT_B_ID="" +``` + #### Update Hermes configuration By default, Hermes will attempt to relay packets on all channels between the chains listed in its configuration file. @@ -396,7 +396,7 @@ You can see more details of Hermes at [the official documentation](https://herme In order to keep IBC channels open for transfers, they must have active IBC clients. An IBC client on chain A references the state of chain B, and vice versa. These clients must be regularly updated to maintain trust guarantees; if they are -allowed to lapse, the client will enter an 'expired' state and no further IBC transfers will be allowed on that channel +allowed to lapse, the client will enter an 'expired' state, and no further IBC transfers will be allowed on that channel until the client is revived through governance. Whenever Hermes relays an IBC transfer, it will automatically update the clients on both chains. However, since reviving @@ -419,7 +419,7 @@ You're now ready to test [transferring assets between the two chains.](../users/ ## Testing with local Namada chains The script `setup-namada` in the Heliax Hermes repo will set up two chains, each with one validator node, copy necessary files for Hermes, -and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` +and make an account for Hermes on each ledger. Also, it will make a Hermes config file `config_for_namada.toml` in the `hermes` directory. First, you will need to export some environment variables: @@ -436,7 +436,7 @@ cd hermes ./scripts/setup-namada $NAMADA_DIR ``` -In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#create-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. +In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#creating-an-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. ```bash copy # create a channel hermes --config $HERMES_CONFIG \ @@ -451,7 +451,7 @@ hermes --config $HERMES_CONFIG \ hermes --config $HERMES_CONFIG start ``` -Each node data and configuration files are in `hermes/data/namada-*/.namada`. +Each node's data and configuration files are in `hermes/data/namada-*/.namada`. In order to close any ledgers setup by the script, one can run ```bash copy