Relay on Mainnet
Last updated
Was this helpful?
Last updated
Was this helpful?
Note This guide is based on the .
The Inter-Blockchain Communication (IBC) protocol enables different blockchains to communicate and transfer assets seamlessly. Relayers serve as intermediaries that facilitate this communication by relaying packets of data between interconnected chains. A relayer process monitors for updates on opens paths between sets of 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 packet relaying, relayers play a vital role in establishing and managing connections, channels, and clients between various blockchains. This functionality fosters seamless interoperability and facilitates asset transfers across different networks.
Additional information on how IBC works can be found .
Minimum RAM requirement:
4 GB RAM
50 GB SSD
2 CPU
Recommended:
8 GB RAM
100 GB SSD
4 CPU
Operating System:
Recommended OS: Linux(x86_64)
Others: Windows/MacOS(x86)
Ensure you have installed the required prerequisites before setting up the Cosmos Go Relayer. 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.
Remove any previous installation:
Add the Go PPA to Your System:
First, add the longsleep/golang-backports PPA to your system. This repository contains the latest version of Go. You can add it by running the following command in your terminal:
Update Your Package List:
After adding the PPA, update your package list to include the latest packages available in the repository:
Install Go:
Now, install Go using the apt package manager. This command will install the latest version of Go available in the PPA:
Check Go is installed correctly (sample output: go version go1.19.4 linux/amd64):
Set $GOPATH:
Open the .profile file, where all your environment variables are stored:
Scroll down to the end of the file and add the following line before export $PATH:
Add the following line to PATH (i.e. export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin):
Reload the PATH environment variable:
Create the directories we set in PATH:
Install Git:
Verify git is installed correctly:
After installing the binary, verify its installation by executing the following command.
\
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.yaml file 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.
Default config file location: ~/.relayer/config/config.yaml
By default, transactions will be relayed with a memo of rly(VERSION) e.g. rly(v2.0.0).
To customize the memo for all relaying, use the --memo flag when initializing the configuration.
Custom memos will have rly(VERSION) appended. For example, a memo of My custom memo running on relayer version v2.0.0 would result in a transaction memo of My custom memo | rly(v2.0.0).
Additionally, the memo can be changed anytime in the following file: ~/.relayer/config/config.yaml
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.
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-addr setting.
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).
Note
key-nameis an identifier of your choosing.
If you need to generate a new private key, use the following command. Remember to replace key-name -> e.g. rly keys add persistence "MyRandomKeyName"
If you already have a private key and want to restore it from your mnemonic you can use the following command. Remember to replace key-name.
Before continuing, ensure your keys have been successfully added by running the following command. You can also check the ~/.relayer/keys folder and observe the contents.
config.yamlExample:
After sending some tokens, you can query the balance of each configured key by running:
Note Thinking of chains in the config as "source" and "destination" can be confusing. Be aware that most paths are bi-directional.
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 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:
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.
~/.relayer/config/config.yaml look?To aid in the setup of the configuration file, we've provided an example on how a relayer configuration file should look.
Example:
The Cosmos Go Relayer code is available at the . 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 of this guide.
The command should output a similar message. If you're seeing an error, ensure you have correctly .
The following command fetches chain metadata from the and adds it to your config file.
NOTE: rly chains add will check the liveliness of the available RPC endpoints for that chain in the . 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 ~/.relayer/config/config.yaml.
You can check available Gravity Bridge RPC endpoints and available Persistence RPC endpoints .
NOTE: This step is necessary if you chose a key-name other than "default" in the . Be aware you need to replace the key names for both chains - Gravity Bridge and Persistence.
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 . After acquiring some tokens, you need to send them to the addresses obtained by running the following commands:
We have the chain metadata configured, now we need path metadata. For more info on path terminology visit .
Use the following command to retrieve IBC path metadata from the and add these paths to your config file.
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 .