Run an IBC Relayer

Running an IBC Relayer for BitNet

Inter-Blockchain Communication (IBC) enables BitNet to securely send tokens and data to other chains in the Cosmos ecosystem. Relayers are off-chain agents that listen for packets on one chain and transmit them to the other.

This guide walks you through setting up an IBC relayer between BitNet and another IBC-enabled chain using Hermes.

What is an IBC Relayer?

An IBC relayer:

  • Connects two blockchain networks.

  • Listens for IBC packets on one chain.

  • Relays those packets to the destination chain.

  • Requires full nodes for both chains and funds for gas fees.

Minimum Requirements

  • 4+ physical CPU cores (8 threads)

  • 32 GB RAM

  • 1TB+ NVMe SSD

  • High open file limits (adjust ulimit -n)

Prerequisites

  • A running BitNet full node (see earlier guides).

  • A full node for the counterparty chain (e.g., Cosmos Hub).

  • Port configuration for both nodes to avoid conflicts.

  • Funds in both chains for relayer fees.

Step 1: Configure Nodes

BitNet Node (~/.bitnetd/config/):

  • app.toml:

[grpc]
enable = true
address = "0.0.0.0:9090"

  • config.toml:

pprof_laddr = "localhost:6060"
[rpc]
laddr = "tcp://127.0.0.1:26657"
[p2p]
laddr = "tcp://0.0.0.0:26656"

Counterparty Node (e.g., Cosmos Hub):

  • Offset ports to avoid collision:

grpc = "0.0.0.0:9092"
pprof_laddr = "localhost:6062"
rpc = "tcp://127.0.0.1:26757"
p2p = "tcp://0.0.0.0:26756"

Step 2: Install Hermes

Install Rust & dependencies:

curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
sudo apt install build-essential git pkg-config libssl-dev librust-openssl-dev

Clone and build 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

Create Hermes config folders:

mkdir -p ~/.hermes/config ~/.hermes/keys
cp config.toml ~/.hermes/

Step 3: Configure Hermes

Edit ~/.hermes/config.toml and set up both chains:

[[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']]

[[chains]]
id = 'bitnet-mainnet'
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']]

Step 4: Add Relayer Keys

Use your mnemonic for both chains:

hermes keys restore cosmoshub-4 -m "your 24-word mnemonic"
hermes keys restore bitnet-mainnet -m "your 24-word mnemonic"

Ensure both accounts have enough tokens to cover transaction fees.

Step 5: Validate & Start

hermes config validate
hermes health-check
hermes start

You’ll see logs showing relayed packets.

Step 6: Maintenance & Monitoring

Query unreceived packets:

hermes query packet unreceived-packets cosmoshub-4 transfer channel-292
hermes query packet unreceived-packets bitnet-mainnet transfer channel-3

Clear stuck packets:

hermes clear packets cosmoshub-4 transfer channel-292
hermes clear packets bitnet-mainnet transfer channel-3
PreviousMainnet

Last updated