# Relayer Operator Guide
### Relayer
### 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](https://ibcprotocol.org/) 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](https://ibc.cosmos.network/).
### Table Of Contents
* [Basic Usage - Relaying Across Chains](#basic-usage-relaying-packets-across-chains)
* [Create Path Across Chains](https://github.com/cosmos/relayer/blob/main/docs/create-path-across-chain.md)
* [Advanced Usage](https://github.com/cosmos/relayer/blob/main/docs/advanced_usage.md)
* [Troubleshooting](https://github.com/cosmos/relayer/blob/main/docs/troubleshooting.md)
* [Features](https://github.com/cosmos/relayer/blob/main/docs/features.md)
* [Relayer Terminology](https://github.com/cosmos/relayer/blob/main/docs/terminology.md)
* [Recommended Pruning Settings](https://github.com/cosmos/relayer/blob/main/docs/node_pruning.md)
***
### Basic Usage - Relaying Packets Across Chains
> The `-h` (help) flag tailing any `rly` command will be your best friend. USE THIS IN YOUR RELAYING JOURNEY.
***
1. **Clone, checkout and install the latest release (**[**releases page**](https://github.com/ConsiderItDone/relayer/releases)**).** [*Go*](https://go.dev/doc/install) *needs to be installed and a proper Go environment needs to be configured*
```shell
$ git clone https://github.com/ConsiderItDone/relayer.git
$ cd relayer && git checkout main
$ make install
```
2. **Initialize the relayer's configuration directory/file.**
```shell
$ 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.5.2)`. To customize the memo for all relaying, use the `--memo` flag when initializing the configuration.
```shell
$ 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.5.2` would result in a transaction memo of `My custom memo | rly(v2.5.2)`. The `--memo` flag is also available for other `rly` commands also that involve sending transactions such as `rly tx link` and `rly start`. It can be passed there to override the `config.yaml` value if desired. To omit the memo entirely, including the default value of `rly(VERSION)`, use `-` for the memo.
3. **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.\
The `rly chains add` command fetches chain meta-data from the [chain-registry](https://github.com/cosmos/chain-registry) and adds it to your config file.
```shell
$ rly chains add cosmoshub slide
```
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 want to manually add the chain config. To add the chain config files manually, example config files have been included [here](https://github.com/cosmos/relayer/tree/main/docs/example-configs/)
```shell
$ rly chains add --url https://raw.githubusercontent.com/cosmos/relayer/main/docs/example-configs/cosmoshub-4.json cosmoshub
```
Slide config example
```yaml
global:
api-listen-addr: :5183
timeout: 10s
memo: ""
light-cache-size: 20
log-level: ""
ics20-memo-limit: 0
max-receiver-size: 0
chains:
slide:
type: avalanche
value:
rpc-addr: http://127.0.0.1:9650/ext/bc/2qdf414xEdWsmjSK1Q59Gautq6fERXbXm4jJnJkZ6MfFBB6PaH/rpc
base-rpc-addr: http://127.0.0.1:9650
subnet-id: 2c1CbR7FGYdeFPB4WaeWphHZrChLH7TQ92FRW6U4mCWTnaxVsB
blockchain-id: 2qdf414xEdWsmjSK1Q59Gautq6fERXbXm4jJnJkZ6MfFBB6PaH
chain-id: "slide"
network-id: 1337
timeout: 10s
contract-address: 0x0300000000000000000000000000000000000002
transferrer-address: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25
key-directory: ~.relayer/keys/avalanche-slide
key: testkey
keyring-backend: test
extra-codecs: []
min-loop-duration: 0s
ibcgo:
type: cosmos
value:
key-directory: ~/.relayer/keys/ibcgo
key: testkey
chain-id: ibcgo
rpc-addr: http://localhost:26657
account-prefix: cosmos
keyring-backend: test
dynamic-gas-price: false
gas-adjustment: 1.5
gas-prices: 0.025stake
min-gas-amount: 0
max-gas-amount: 0
debug: true
timeout: 10s
block-timeout: ""
output-format: json
sign-mode: direct
extra-codecs: []
coin-type: null
signing-algorithm: ""
broadcast-mode: batch
min-loop-duration: 0s
extension-options: []
feegrants: null
paths:
demo:
src:
chain-id: slide
dst:
chain-id: ibcgo
src-channel-filter:
rule: ""
channel-list: []
demo2:
src:
chain-id: ibcgo
dst:
chain-id: slide
src-channel-filter:
rule: ""
channel-list: []
```
4. **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.
```shell
$ rly keys add ibcgo [key-name]
$ rly keys add slide [key-name]
```
If you already have a private key and want to restore it from your mnemonic you can use the `restore` subcommand.
```shell
$ rly keys restore ibcgo [key-name] "mnemonic words here"
$ rly keys restore slide [key-name] "mnemonic words here"
```
5. **Use the `key-name` created above.**
> This step is necessary if you chose a `key-name` other than "default"
```shell
$ rly keys use ibcgo [key-name]
$ rly keys use slide [key-name]
```
6. **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:
```shell
$ rly q balance ibcgo
$ rly q balance slide
```
7. **Configure path meta-data in config file.**\
We have the chain meta-data configured, now we need path meta-data. For more info on `path` terminology visit [here](https://github.com/cosmos/relayer/blob/main/docs/troubleshooting.md).
> NOTE: Thinking of chains in the config as "source" and "destination" can be confusing. Be aware that most path are bi-directional.
>
>
`rly paths fetch` will check for IBC path meta data from the [chain-registry](https://github.com/cosmos/chain-registry/tree/master/_IBC) and add these paths to your config file.
```shell
$ 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!
8. **Configure the channel filter.**
By default, the relayer will relay packets over all channels on a given connection.\
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 Cosmos Hub and Landslide our filter settings would look like the following.\
Example:
```yaml
hubslide:
src:
chain-id: ibcgo
client-id: 07-tendermint-259
connection-id: connection-257
dst:
chain-id: slide
client-id: 14-avalanche-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. If you only know the "dst" channel-ID you can query the "src" channel-ID by running: `rly q channel | jq '.channel.counterparty.channel_id'`
9. **Finally, we start the relayer on the desired path.** The relayer will periodically update the clients and listen for IBC messages to relay.
```shell
$ rly paths list
$ rly start [path]
# Optionally you can omit the `path` argument to start all configured paths
$ rly start
```
> 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.
\[[TROUBLESHOOTING](https://github.com/cosmos/relayer/blob/main/docs/troubleshooting.md)]
***
[Create Path Across Chains -->](https://github.com/cosmos/relayer/blob/main/docs/create-path-across-chain.md)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.landslide.network/product-guides/ibc-light-client/relayer-operator-guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.