Relayer

In IBC, blockchains do not directly pass messages to each other over the network. This is where relayer comes in. A relayer process monitors for updates on opens paths between sets of IBC enabled chains. The relayer submits these updates in the form of specific message types to the counterparty chain. Clients are then used to track and verify the consensus state.

In addition to relaying packets, this relayer can open paths across chains, thus creating clients, connections and channels.

Additional information on how IBC works can be found here.

Relayer	IBC-Go
v1.0.0	ibc-go v1, ibc-go v2
v2.0.0	ibc-go v3

**If you are updating the relayer from any version prior to v2.0.0-rc1, your current config file is not compatible. See: config_migration

---

Table Of Contents

• Basic Usage - Relaying Across Chains
• Create Path Across Chains
• Troubleshooting
• Features
• Relayer Terminology
• Recommended Pruning Settings
• Demo

---

Basic Usage - Relaying Packets Across Chains

The -h (help) flag tailing any rly command will be your best friend. USE THIS IN YOUR RELAYING JOURNEY.

---

1. Clone, checkout and install the latest release (releases page).

   Go needs to be installed and a proper Go environment needs to be configured

   $ git clone https://github.com/cosmos/relayer.git
   $ cd relayer
   $ make install

2. Initialize the relayer's configuration directory/file.

   $ rly config init --memo "Zuka#5870"

   The --memo flag is also available for other rly commands also that involve sending transactions such as rly tx link and rly start. It can be passed there to override the config.yaml value if desired.

   To omit the memo entirely, including the default value of rly(VERSION), use - for the memo.

3. Configure the chains you want to relay between.

   To add the chain config files manually, example config files have been included here

     rly chains add --url https://raw.githubusercontent.com/zukaman/relayer/main/configs/stride/stride.json stride
     rly chains add --url https://raw.githubusercontent.com/zukaman/relayer/main/configs/stride/GAIA.json GAIA
   

4. Import OR create new keys for the relayer to use when signing and relaying transactions.

   key-name is an identifier of your choosing.

   If you need to generate a new private key you can use the add subcommand.

   $ rly keys add stride [key-name]  
   $ rly keys add GAIA [key-name]  

   If you already have a private key and want to restore it from your mnemonic you can use the restore subcommand.

   $ rly keys restore stride [key-name] "mnemonic words here"
   $ rly keys restore GAIA [key-name] "mnemonic words here"

5. Edit the relayer's key values in the config file to match the key-name's chosen above.

   This step is necessary if you chose a key-name other than "default"

   Example:

   - type: cosmos
      value:
      key: YOUR-KEY-NAME-HERE
      chain-id: cosmoshub-4
      rpc-addr: http://localhost:26657

6. Ensure the keys associated with the configured chains are funded.

   Your configured addresses will need to contain some of the respective native tokens for paying relayer fees.

   
   You can query the balance of each configured key by running:

   $ rly q balance stride
   $ rly q balance GAIA

7. Configure path meta-data in config file.

8. Configure the channel filter.

   By default, the relayer will relay packets over all channels on a given connection.
   
   Each path has a src-channel-filter which you can utilize to specify which channels you would like to relay on.
   
   The rule can be one of three values:

   • allowlist which tells the relayer to relay on ONLY the channels in channel-list
   • denylist which tells the relayer to relay on all channels BESIDES the channels in channel-list
   • empty value, which is the default setting, and tells the relayer to relay on all channels
   
   

   Since we are only worried about the canonical channel between the Cosmos Hub and Osmosis our filter settings would look like the following.
   
   Example:

   hubosmo:
      src:
          chain-id: cosmoshub-4
          client-id: 07-tendermint-259
          connection-id: connection-257
      dst:
          chain-id: osmosis-1
          client-id: 07-tendermint-1
          connection-id: connection-1
      src-channel-filter:
              rule: allowlist
              channel-list: [channel-141]  

   Because two channels between chains are tightly coupled, there is no need to specify the dst channels. If you only know the "dst" channel-ID you can query the "src" channel-ID by running: rly q channel <dst_chain_name> <dst_channel_id> <port> | jq '.channel.counterparty.channel_id'

9. Finally, we start the relayer on the desired path.

   The relayer will periodically update the clients and listen for IBC messages to relay.

   $ rly paths list
   $ rly start [path]

   You will need to start a separate shell instance for each path you wish to relay over.

   When running multiple instances of rly start, you will need to use the --debug-addr flag and provide an address:port. You can also pass an empty string '' to turn off this feature or pass localhost:0 to randomly select a port.

   ---

   [TROUBLESHOOTING]

---

Security Notice

If you would like to report a security critical bug related to the relayer repo, please reach out @jackzampolin or @Ethereal0ne on telegram.

Code of Conduct

The Cosmos community is dedicated to providing an inclusive and harassment free experience for contributors. Please visit Code of Conduct for more information.

---

Create Path Across Chains -->