# Go Relayer
Before you dive into Go relayers, make sure to:
- Install Go.
- Install Docker.
- Install Rust.
For all installations, please see the setup page.
Have you considered running a relayer?
In this section, you will learn:
- How to get started with the Go relayer
- Basic Go relayer commands
The Go relayer (opens new window) is a relayer implementation written in Golang. It can create clients, connections, and channels, as well as relay packets, and update and upgrade clients.
The Go relayer aims to get your relayer up and running with minimal manual configuration and abstracts away a lot of the more complex IBC concepts. The objective is that users can spin up their own relayer and relay packets. To provide this functionality, it automates a lot of work to fetch configuration data from the chain registry.
After the installation, you will get started with relaying on mainnet chains and do some local testing.
# Installation and getting started
The repository offers a script to start two chains, which we need to test the relayer.
First, create a folder for this section:
Clone the Go relayer repository (opens new window):
Now clone the Gaia (opens new window) repository into it:
Now build the Go relayer:
Make sure that your
$GOPATH is set correctly and
$GOPATH/bin is included in your
To check the available commands, run the help command on the
Notice how the categories reflect the requirements you saw in the last section: to manage chain and path information, manage keys, query, and transact. The configuration data is added to the config file, stored at
$HOME/.relayer/config/config.yaml by default. If this is the first time you run the relayer, first initialize the config with the following command:
Now you are all set to add the chains and paths you want to relay on, add your keys and start relaying. You will investigate two different scenarios: setting up a relayer between two chains on the mainnet (this would enable you to start relaying in production), and setting up two local chains for testing purposes.
# Relaying in production
As stated earlier, the Go relayer strives to get your relayer up and running in a short amount of time. You will follow the tutorial from the Github repository (opens new window) to start relaying between the Cosmos Hub and Osmosis, one of the most popular paths.
Configure the chains you want to relay between.
In this example, you will configure the relayer to operate on the canonical path between the Cosmos Hub and Osmosis.
rly chains addcommand fetches chain meta-data from the chain registry (opens new window) and adds it to your config file:
Adding chains from the chain registry randomly selects a publicly available RPC address from the registry entry. If you are running your own node (which is recommended if you are running relaying services professionally), manually go into the config and adjust the
rpc-addrsetting to the RPC endpoint you have exposed.
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 in the Cosmos relayer documentation (opens new window).
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 the
- If you already have a private key and want to restore it from your mnemonic you can use the
- If you need to generate a new private key you can use the
Edit the relayer's
keyvalues in the config file to match the
key-names chosen above.
This step is necessary if you chose a
key-nameother than "default".
Ensure the keys associated with the configured chains are funded.
ATTENTION: Your configured addresses will need to contain some of the respective native tokens to pay relayer fees.
You can query the balance of each configured key by running:
Configure path meta-data in the config file.
You configured the chain meta-data, now you need path meta-data. This scenario assumes that there is already a canonical channel, so there is no need for light client creation, nor connection and channel handshakes to set these up.
There is one easy command to get this path information - initially from the Interchain folder (opens new window) in the Go relayer repository, but this will soon be replaced by IBC data in the chain registry (opens new window).
Don't see the path metadata for paths you want to relay on? Please open a Push Request (PR) to add this metadata to the GitHub repository!
At minimum, this command will add two paths. In our case it will add one path from the Cosmos Hub to Osmosis, and another path from Osmosis to the Cosmos Hub.
Configure the channel filter.
By default, the relayer will relay packets over all channels on a given connection.
Each path has an
src-channel-filter, which you can utilize to specify which channels you would like to relay on.
rulecan be one of three values:
allowlist, which tells the relayer to relay on ONLY the channels in
denylist, which tells the relayer to relay on all channels EXCEPT the channels in
- Empty value, which is the default setting and tells the relayer to relay on all channels.
Since you should be only worried about the canonical channel between the Cosmos Hub and Osmosis, our filter settings would look like the following:
Because two channels between chains are tightly coupled, there is no need to specify the dst channels.
Do a status check.
Before starting to relay and after making some changes to the config, you can check the status of the chains and paths in the config:
In case one of the checks receives a
✔, you will need to check if you completed all the previous steps correctly.
Finally, start the relayer on the desired path.
The relayer will periodically update the clients and listen for IBC messages to relay.
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-addrflag and provide an
address:port. You can also pass an empty string
''to turn off this feature, or pass
localhost:0to randomly select a port.
# Testing locally
Besides running a relayer between mainnet chains, you can also run a relayer between public testnet chains or locally run chains to do some testing of particular scenarios. Here you will use two local
gaia chains and run a relayer between them. This is based on the demo in the Go relayer repository (opens new window).
Make sure you are in the
relayer folder. Now use the offered script to spin up two chains, ibc-0 and ibc-1, which will run in the background.
This script will remove the
~/.relayer folder with your current config. Copy it to another folder if you want to keep your current config.
To stop, use
--home directory is now ready for normal operations between ibc-0 and ibc-1.
It is helpful to examine the folder structure of the relayer:
There you can see the addresses of the users created by the script.
Check the relayer configuration with:
Now see if the chains and path(s) are ready to relay over:
You can now connect the two chains with the
link command. Note that if any clients, connections, and channels were not previously created (which would have shown up in the previous status check) the
link command will attempt to create the missing objects. You can also check
rly tx -h to find out the separate commands for these actions.
Next, check the token balances on both chains:
Finally, send some tokens between the chains:
Now you have created the commitment proof on ibc-0 to send the packet, but no relaying has taken place yet.
# Relay packets/acknowledgments
rly start demo essentially loops these two commands:
Check that the transfer has completed:
Send the tokens back to the account on ibc-0:
Check that the return trip has completed:
You can see that the stake balances decreased on each chain because of the set fees in the configuration.