Comment on page
Relay on Mainnet
In IBC, blockchains do not directly pass messages to each other over the network. This is where a
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.
- Minimal:
- 4 GB RAM
- 50 GB SSD
- 2 CPU
- Recommended:
- 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
- 2.
- 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
.profile
file, 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.
export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
):$GOPATH/bin - 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.
rly version
The command should output a similar message. If you're seeing an error, ensure you have correctly installed and setup Go.
version: v2.2.0-rc3
commit: unknown
cosmos-sdk: v0.46.6
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.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.rly config init
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.rly config init --memo "My custom memo"
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)
.Aditionally, 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.
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
rpc-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 be required to manually change the RPC endpoints in ~/.relayer/config/config.yaml
.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).
Notekey-name
is 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"
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
key-name
.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/keys
folder and observe the contents.rly keys list gravitybridge
rly keys list persistence
NOTE: This step is necessary if you chose a
key-name
other than "default" in the previous step. Be aware you need to replace the key names for both chains - Gravity Bridge and Persistence.Example:
- type: cosmos
value:
key: YOUR-KEY-NAME-HERE # e.g.MyRandomKeyName
chain-id: core-1
rpc-addr: https://persistence-mainnet-rpc.cosmonautstakes.com:443
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
path
terminology 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-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 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 Gravity Bridge and Persistence our filter settings would look like the following.
gravitybridge-persistence:
src:
chain-id: gravity-bridge-3
client-id: 07-tendermint-39
connection-id: connection-50
dst:
chain-id: core-1
client-id: 07-tendermint-51
connection-id: connection-49
src-channel-filter:
rule: allowlist
channel-list: [channel-24]
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
rly start
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-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.To aid in the setup of the configuration file, we've provided an example on how a relayer configuration file should look.
Example:
global:
api-listen-addr: :5183
timeout: 10s
memo: You have been relayed by Cosmonaut Stakes
light-cache-size: 20
chains:
gravitybridge:
type: cosmos
value:
key: CosmonautStakesRelayerKey
chain-id: gravity-bridge-3
rpc-addr: https://gravity-rpc.polkachu.com:443
account-prefix: gravity
keyring-backend: test
gas-adjustment: 1.2
gas-prices: 0.01ugraviton
min-gas-amount: 1
debug: false
timeout: 20s
output-format: json
sign-mode: direct
extra-codecs: []
persistence:
type: cosmos
value:
key: CosmonautStakesRelayerKey
chain-id: core-1
rpc-addr: https://persistence-mainnet-rpc.cosmonautstakes.com:443
account-prefix: persistence
keyring-backend: test
gas-adjustment: 1.2
gas-prices: 0.01uxprt
min-gas-amount: 1
debug: false
timeout: 20s
output-format: json
sign-mode: direct
extra-codecs: []
paths:
gravitybridge-persistence:
src:
chain-id: gravity-bridge-3
client-id: 07-tendermint-39
connection-id: connection-50
dst:
chain-id: core-1
client-id: 07-tendermint-51
connection-id: connection-49
src-channel-filter:
rule: allowlist
channel-list: [channel-24]
Last modified 3mo ago