> ## Documentation Index
> Fetch the complete documentation index at: https://sidiorresearchlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an IBC Relayer

# Run an IBC Relayer

## What is an IBC Relayer?

An IBC relayer is a software component that facilitates communication between two distinct blockchain networks that
support the Inter-Blockchain Communication (IBC) protocol. The IBC protocol is a standard for the secure and reliable
transfer of digital assets and data across different blockchain networks.

An IBC relayer is responsible for relaying IBC packets, which are used to send messages and data between two different
blockchain networks. It receives packets from one chain, verifies their authenticity and validity, and then relays
them to the receiving chain.

## Minimum Requirements

* 8 core (4 physical core), x86\_64 architecture processor
* 32 GB RAM (or equivalent swap file set up)
* 1 TB+ nVME drives

If running many nodes on a single VM, [ensure your open files limit is increased](https://tecadmin.net/increase-open-files-limit-ubuntu/).

## Prerequisites

Before beginning, ensure you have an HyperPaxeer node running in the background of the same machine that you intend to relay on.
Follow [this guide](./../protocol/Paxeer-Network-cli/single-node) to set up an HyperPaxeer node if you have not already.

In this guide, we will be relaying between [HyperPaxeer (channel-3) and Cosmos Hub (channel-292)](https://www.mintscan.io/Paxeer-Network/relayers).
When setting up your HyperPaxeer and Cosmos full nodes, be sure to offset the ports being used in both the `app.toml` and `config.toml`
files of the respective chains (this process will be shown below).

In this example, the default ports for HyperPaxeer will be used, and the ports of the Cosmos Hub node will be manually changed.

## HyperPaxeer Daemon Settings

First, set `grpc server` on port `9090` in the `app.toml` file from the `$HOME/.hyperpaxd/config` directory:

```bash theme={null}
vim $HOME/.hyperpaxd/config/app.toml
```

```bash theme={null}
[grpc]

# Enable defines if the gRPC server should be enabled.
enable = true

# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9090"
```

Then, set the `pprof_laddr` to port `6060`, `rpc laddr` to port `26657`, and `prp laddr` to `26656` in the `config.toml`
file from the `$HOME/.hyperpaxd/config` directory:

```bash theme={null}
vim $HOME/.hyperpaxd/config/config.toml
```

```bash theme={null}
# pprof listen address (https://golang.org/pkg/net/http/pprof)
pprof_laddr = "localhost:6060"
```

```bash theme={null}
[rpc]

# TCP or UNIX socket address for the RPC server to listen on
laddr = "tcp://127.0.0.1:26657"
```

```bash theme={null}
[p2p]

# Address to listen for incoming connections
laddr = "tcp://0.0.0.0:26656"
```

## Cosmos Daemon Settings

First, set `grpc server` to port `9090` in the `app.toml` file from the `$HOME/.gaiad/config` directory:

```bash theme={null}
vim $HOME/.gaiad/config/app.toml
```

```bash theme={null}
[grpc]

# Enable defines if the gRPC server should be enabled.
enable = true

# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9092"
```

Then, set the `pprof_laddr` to port `6062`, `rpc laddr` to port `26757`, and `prp laddr` to `26756` in the `config.toml`
file from the `$HOME/.gaiad/config` directory:

```bash theme={null}
vim $HOME/.gaiad/config/app.toml
```

```bash theme={null}
# pprof listen address (https://golang.org/pkg/net/http/pprof)
pprof_laddr = "localhost:6062"
```

```bash theme={null}
[rpc]

# TCP or UNIX socket address for the RPC server to listen on
laddr = "tcp://127.0.0.1:26757"
```

```bash theme={null}
[p2p]

# Address to listen for incoming connections
laddr = "tcp://0.0.0.0:26756"
```

## Install Rust Dependencies

Install the following rust dependencies:

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

```bash theme={null}
source $HOME/.cargo/env
sudo apt-get install pkg-config libssl-dev
```

```bash theme={null}
sudo apt install librust-openssl-dev build-essential git
```

## Build & Setup Hermes

Create the directory where the binary will be placed, clone the hermes source repository, and build it using the latest release.

```bash theme={null}
mkdir -p $HOME/hermes
git clone https://github.com/informalsystems/ibc-rs.git hermes
cd hermes
git checkout v0.12.0
cargo install ibc-relayer-cli --bin hermes --locked
```

Make the hermes `config` and `keys` directory, and copy `config.toml` to the config directory:

```bash theme={null}
mkdir -p $HOME/.hermes
mkdir -p $HOME/.hermes/keys
cp config.toml $HOME/.hermes
```

Check the hermes version and configuration directory setup:

```bash theme={null}
$ hermes version
INFO ThreadId(01) using default configuration from '/home/relay/.hermes/config.toml'
hermes 0.12.0
```

Edit the hermes configuration (use ports according the port configuration set above, adding only chains that will be relayed):

```bash theme={null}
vim $HOME/.hermes/config.toml
```

```bash theme={null}
# In this example, we will set channel-292 on the cosmoshub-4 chain settings and channel-3 on the HyperPaxeer_9001-2 chain settings:
[[chains]]
id = 'cosmoshub-4'
rpc_addr = 'http://127.0.0.1:26757'
grpc_addr = 'http://127.0.0.1:9092'
websocket_addr = 'ws://127.0.0.1:26757/websocket'
...
[chains.packet_filter]
policy = 'allow'
list = [
   ['transfer', 'channel-292'], # HyperPaxeer_9001-2
]

[[chains]]
id = 'HyperPaxeer_9001-2'
rpc_addr = 'http://127.0.0.1:26657'
grpc_addr = 'http://127.0.0.1:9090'
websocket_addr = 'ws://127.0.0.1:26657/websocket'
...
address_type = { derivation = 'ethermint', proto_type = { pk_type = '/ethermint.crypto.v1.ethsecp256k1.PubKey' } }
[chains.packet_filter]
policy = 'allow'
list = [
  ['transfer', 'channel-3'], # cosmoshub-4
]
```

Add your relayer wallet to Hermes' keyring (located in `$HOME/.hermes/keys`)

The best practice is to use the same mnemonic over all networks. Do not use your relaying-addresses for anything else,
because it will lead to account sequence errors.

```bash theme={null}
hermes keys restore cosmoshub-4 -m "24-word mnemonic seed"
hermes keys restore HyperPaxeer_9001-2 -m "24-word mnemonic seed"
```

Ensure this wallet has funds in both HyperPaxeer and ATOM in order to pay the fees required to relay.

## Final Checks

Validate your hermes configuration file:

```bash theme={null}
$ hermes config validate
INFO ThreadId(01) using default configuration from '/home/relay/.hermes/config.toml'
Success: "validation passed successfully"
```

Perform the hermes `health-check` to see if all connected nodes are up and synced:

```bash theme={null}
$ hermes health-check
INFO ThreadId(01) using default configuration from '/home/relay/.hermes/config.toml'
INFO ThreadId(01) telemetry service running, exposing metrics at http://0.0.0.0:3001/metrics
INFO ThreadId(01) starting REST API server listening at http://127.0.0.1:3000
INFO ThreadId(01) [cosmoshub-4] chain is healthy
INFO ThreadId(01) [HyperPaxeer_9001-2] chain is healthy
```

When your nodes are fully synced, you can start the hermes daemon:

```bash theme={null}
hermes start
```

Watch hermes' output for successfully relayed packets, or any errors.
It will try and clear any unrecieved packets after startup has completed.

## Helpful Commands

Query hermes for unrecieved packets and acknowledgements (ie. check if channels are "clear") with the following:

```bash theme={null}
hermes query packet unreceived-packets cosmoshub-4 transfer channel-292
hermes query packet unreceived-acks cosmoshub-4 transfer channel-292
```

```bash theme={null}
hermes query packet unreceived-packets HyperPaxeer_9001-2 transfer channel-3
hermes query packet unreceived-acks HyperPaxeer_9001-2 transfer channel-3
```

Query hermes for packet commitments with the following:

```bash theme={null}
hermes query packet commitments cosmoshub-4 transfer channel-292
hermes query packet commitments HyperPaxeer_9001-2 transfer channel-3
```

Clear the channel (only works on hermes `v0.12.0` and higher) with the following:

```bash theme={null}
hermes clear packets cosmoshub-4 transfer channel-292
hermes clear packets HyperPaxeer_9001-2 transfer channel-3
```

Clear unrecieved packets manually
(experimental, will need to stop hermes daemon to prevent confusion with account sequences)
with the following:

```bash theme={null}
hermes tx raw packet-recv HyperPaxeer_9001-2 cosmoshub-4 transfer channel-292
hermes tx raw packet-ack HyperPaxeer_9001-2 cosmoshub-4 transfer channel-292
hermes tx raw packet-recv cosmoshub-4 HyperPaxeer_9001-2 transfer channel-3
hermes tx raw packet-ack cosmoshub-4 HyperPaxeer_9001-2 transfer channel-3
```