Relay on Mainnet
In IBC, blockchains do not directly pass messages to each other over the network. This is where a
relayercomes 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.
- 4 GB RAM
- 50 GB SSD
- 2 CPU
- 8 GB RAM
- 100 GB SSD
- 4 CPU
- Operating System:
- Recommended: Linux(x86_64)
- Others: Windows/MacOS(x86)
To successfully run a Cosmos Go Relayer, we need to install some prerequirements. Because running the Cosmos Go Relayer software depends on them, prerequirements are also known as dependencies.
We need to install and setup one dependency - Go.
- 1.Remove any previous installation:rm -rf /usr/local/go
- 3.Download the latest version of Go (1.19.4 as of time of writing):wget https://go.dev/dl/go1.19.4.linux-amd64.tar.gz
- 4.Extract the contents of the archive into /usr/local:tar -C /usr/local -xzf go1.19.4.linux-amd64.tar.gz
- 5.Check Go is installed correctly (sample output:
go version go1.19.4 linux/amd64):go version
- 6.Set $GOPATH:
- 1.Open the
.profilefile, where all your environment variables are stored:nano ~/.profile
- 2.Scroll down to the end of the file and add the following line before
export $PATH:export GOPATH=$HOME/go
- 3.Add the following line to PATH (i.e.
- 4.Reload the PATH environment variable:source ~/.profile
- 5.Create the directories we set in PATH:mkdir -p $GOPATH/bin
- 1.Install Git:apt install git
- 2.Verify git is installed correctly:git --version # Sample Output: git version 2.34.1
The Cosmos Go Relayer code is available at the Official GitHub Repository. First, we must 'download' all the code locally by cloning the GitHub repository, choosing the latest version (as of time of writing: v5.0.0) and installing the binary into our GOPATH as explained in the prerequisites section of this guide.
git clone https://github.com/cosmos/relayer.git # Download all the code locally
cd relayer && git checkout v5.0.0 # Choose the latest version
make install # Install the Cosmos Go Relayer (creates a binary in GOPATH)
Next, verify the binary is correctly installed by running the following command.
The command should output a similar message. If you're seeing an error, ensure you have correctly installed and setup Go.
go: go1.18.3 linux/amd64
After the relayer binary is correctly installed, it needs to be locally initialized. The following command creates a configuration location (available at
~/.relayer), containing a
config/config.yamlfile specifying how the relayer should run (chains, channels, etc.).
Later on, when the keys are added, an extra folder is created. This folder is available at
~/.relayer/keys. This is the default keys storage location for all the chains you relay between.
rly config init
Default config file location:
By default, transactions will be relayed with a memo of
To customize the memo for all relaying, use the
--memoflag when initializing the configuration.
rly config init --memo "My custom memo"
Custom memos will have
rly(VERSION)appended. For example, a memo of
My custom memorunning on relayer version
v2.0.0would result in a transaction memo of
My custom memo | rly(v2.0.0).
Aditionally, the memo can be changed anytime in the following file:
In our example, we will configure the relayer to operate on the canonical path between Gravity Bridge and Persistence. These chains are chosen solely for the purpose of this guide.
The following command fetches chain metadata from the chain-registry and adds it to your config file.
rly chains add gravitybridge persistence
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
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 be required to manually change the RPC endpoints in
Next, you're required to add an existing key (a.k.a. address) or create a new one. An address is necessary to sign and relay transactions between chains (in our case, Gravity Bridge <-> Persistence).
key-nameis an identifier of your choosing.
If you need to generate a new private key, use the following command. Remember to replace
rly keys add persistence "MyRandomKeyName"
rly keys add gravitybridge [key-name]
rly keys add persistence [key-name]
If you already have a private key and want to restore it from your mnemonic you can use the following command. Remember to replace
rly keys restore gravitybridge [key-name] "mnemonic words here"
rly keys restore persistence [key-name] "mnemonic words here"
Before continuing, ensure your keys have been successfully added by running the following command. You can also check the
~/.relayer/keysfolder and observe the contents.
rly keys list gravitybridge
rly keys list persistence
NOTE: This step is necessary if you chose a
key-nameother than "default" in the previous step. Be aware you need to replace the key names for both chains - Gravity Bridge and Persistence.
- type: cosmos
key: YOUR-KEY-NAME-HERE # e.g.MyRandomKeyName
Your configured addresses will need to contain some of the respective native tokens for paying relayer fees. You can buy XPRT and GRAV on the Osmosis Decentralized Exchange. After acquiring some tokens, you need to send them to the addresses obtained by running the following commands:
rly keys list gravitybridge
rly keys list persistence
After sending some tokens, you can query the balance of each configured key by running:
rly query balance gravitybridge
rly query balance persistence
We have the chain metadata configured, now we need path metadata. 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 paths are bi-directional.
The following command will check for IBC path metadata from the chain-registry and add these paths to your config file.
rly paths fetch
By default, the relayer will relay packets over all channels on a given connection. You can find all open IBC channels between Persistence and other chains here.
Each path has a
src-channel-filterwhich you can utilize to specify which channels you would like to relay on.
rulecan be one of three values:
allowlistwhich tells the relayer to relay on ONLY the channels in
denylistwhich tells the relayer to relay on all channels BESIDES the channels in
- 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 Gravity Bridge and Persistence 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.
The relayer will periodically update the clients and listen for IBC messages to relay.
Since we have setup only one path (Gravity Bridge <-> Persistence), we can start the relayer on the afore-mentioned path by running the following command
If you have multiple paths available (to check run
rly chains list), then you can start relaying on just one path (Gravity Bridge <-> Persistence) by running the following command:
rly start gravitybridge-persistence
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.
To aid in the setup of the configuration file, we've provided an example on how a relayer configuration file should look.
memo: You have been relayed by Cosmonaut Stakes