Relayer Operator Guide
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 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.Table Of Contents
Basic Usage - Relaying Packets Across Chains
The
-h(help) flag tailing anyrlycommand will be your best friend. USE THIS IN YOUR RELAYING JOURNEY.
Clone, checkout and install the latest release (releases page). Go needs to be installed and a proper Go environment needs to be configured
Initialize the relayer's configuration directory/file.
Default config file location:
~/.relayer/config/config.yamlBy default, transactions will be relayed with a memo ofrly(VERSION)e.g.rly(v2.5.2). To customize the memo for all relaying, use the--memoflag when initializing the configuration.Custom memos will have
rly(VERSION)appended. For example, a memo ofMy custom memorunning on relayer versionv2.5.2would result in a transaction memo ofMy custom memo | rly(v2.5.2). The--memoflag is also available for otherrlycommands also that involve sending transactions such asrly tx linkandrly start. It can be passed there to override theconfig.yamlvalue if desired. To omit the memo entirely, including the default value ofrly(VERSION), use-for the memo.Configure the chains you want to relay between. In our example, we will configure the relayer to operate on the canonical path between the Cosmos Hub and Osmosis. The
rly chains addcommand fetches chain meta-data from the chain-registry and adds it to your config file.Adding chains from the chain-registry randomly selects an RPC address from the registry entry. If you are running your own node, manually go into the config and adjust the
rpc-addrsetting.NOTE:
rly chains addwill check the liveliness of the available RPC endpoints for that chain in the chain-registry. It is possible that the command will fail if none of these RPC endpoints are available. In this case, you will want to manually add the chain config. To add the chain config files manually, example config files have been included hereSlide config example
Import OR create new keys for the relayer to use when signing and relaying transactions.
key-nameis an identifier of your choosing. If you need to generate a new private key you can use theaddsubcommand.If you already have a private key and want to restore it from your mnemonic you can use the
restoresubcommand.Use the
key-namecreated above.This step is necessary if you chose a
key-nameother than "default"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:
Configure path meta-data in config file. We have the chain meta-data configured, now we need path meta-data. For more info on
pathterminology visit here.NOTE: Thinking of chains in the config as "source" and "destination" can be confusing. Be aware that most path are bi-directional.
rly paths fetchwill check for IBC path meta data from the chain-registry and add these paths to your config file.NOTE: Don't see the path metadata for paths you want to relay on? Please open a PR to add this metadata to the GitHub repo!
Configure the channel filter.
By default, the relayer will relay packets over all channels on a given connection. Each path has a
src-channel-filterwhich you can utilize to specify which channels you would like to relay on. Therulecan be one of three values:allowlistwhich tells the relayer to relay on ONLY the channels inchannel-listdenylistwhich tells the relayer to relay on all channels BESIDES the channels inchannel-listempty 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 Landslide our filter settings would look like the following. Example:
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'Finally, we start the relayer on the desired path. The relayer will periodically update the clients and listen for IBC messages to relay.
When running multiple instances of
rly start, you will need to use the--debug-addrflag and provide an address:port. You can also pass an empty string''to turn off this feature or passlocalhost:0to randomly select a port.
Last updated
