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 |
- Basic Usage - Relaying Across Chains
- Create Path Across Chains
- Troubleshooting
- Features
- Relayer Terminology
- Recommended Pruning Settings
- Demo
The
-h
(help) flag tailing anyrly
command 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
$ git clone https://github.com/cosmos/relayer.git $ git checkout v2.0.0 $ cd relayer && make install
-
Initialize the relayer's configuration directory/file.
$ rly config init
Default config file location:
~/.relayer/config/config.yaml
-
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.
Therly chains add
command fetches chain meta-data from the chain-registry and adds it to your config file.$ rly chains add cosmoshub osmosis
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 therpc-addr
setting.NOTE:
rly chains add
will 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 here
$ rly chains add --url https://raw.githubusercontent.com/cosmos/relayer/main/docs/example-configs/cosmoshub-4.json $ rly chains add --url https://raw.githubusercontent.com/cosmos/relayer/main/docs/example-configs/osmosis-1.json
-
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 cosmoshub-4 [key-name] $ rly keys add osmosis-1 [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 cosmoshub-4 [key-name] "mnemonic words here" $ rly keys restore osmosis-1 [key-name] "mnemonic words here"
-
Edit the relayer's
key
values in the config file to match thekey-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
-
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 cosmoshub-4 $ rly q balance osmosis-1
-
Configure path meta-data in config file.
We have the chain meta-data configured, now we need path meta-data. For more info onpath
terminology visit here.
rly paths fetch
will check for the relevantpath.json
files for ALL configured chains in your config file.
The path meta-data is queried from the interchain directory.$ rly paths fetch
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!At minimum, this command will add two paths, in our case it will add one path from cosmoshub to osmosis and another path from osmosis to cosmoshub.
-
By default, the relayer will relay packets over all channels on a given connection.
Each path has asrc-channel-filter
which you can utilize to specify which channels you would like to relay on.
Therule
can be one of three values:allowlist
which tells the relayer to relay on ONLY the channels inchannel-list
denylist
which tells the relayer to relay on all channels BESIDES the channels inchannel-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.
-
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 or setup .
If you would like to report a security critical bug related to the relayer repo, please reach out @jackzampolin or @Ethereal0ne on telegram.
The Cosmos community is dedicated to providing an inclusive and harassment free experience for contributors. Please visit Code of Conduct for more information.