Hermes
Instructions for setting up the rust based relayer, Hermes

Assumptions

We assume that you already have access to Juno, Osmosis and Cosmos nodes. These can be either local nodes, or you can access them over the network. However, for networked version, you will need to adjust the systemd configuration not to depend on the chains that are run on other servers. And naturally the hermes configuration needs to adjust the addressing of each chain as well.
The given example has all relayed chains run locally, Juno is on standard ports, other chains are configured as follows:
  • Osmosis: 36657 and 39090
  • Cosmos: 46657 and 49090
  • Sifchain: 56657 and 59090
In these instructions, Hermes is installed under /srv/hermes, adjust the paths according to your setup.
These instructions are based on installation on Debian 10, but should work the same on Debian 11 or recent Ubuntu.
You will need rust, build-essential and git installed to follow these instructions.

Building Hermes

For preparation, we will create a dedicated user to run Hermes. Following command will also create home directory for the new user.
1
sudo useradd -m -d /srv/hermes hermes
Copied!
We will next switch to the hermes user and create a directory where we will compile the relayer software.
1
sudo sudo -u hermes -s
2
mkdir /srv/hermes/source
3
mkdir /srv/hermes/bin
4
cd /srv/hermes/source
Copied!
Now is time to clone the source repository and build it. Note that we need to checkout the latest release.
1
git clone https://github.com/informalsystems/ibc-rs.git hermes
2
cd hermes
3
git checkout v0.7.2
4
cargo build --release
5
cp target/release/hermes ~/bin
6
cd
Copied!
Next we will check that the newly built hermes version is the correct one:
1
[email protected]:~$ bin/hermes version
2
Oct 04 15:52:48.299 INFO ThreadId(01) using default configuration from '/srv/hermes/.hermes/config.toml'
3
hermes 0.7.2
Copied!

Configuring Hermes

Choose your favourite editor and edit the following configuration template to mach your setup. There are features like telemetry and rest API that you can enable, but they are not necessary, so they are left out from this tutorial.
1
[global]
2
strategy = 'packets'
3
filter = true
4
log_level = 'info'
5
clear_packets_interval = 100
6
7
#
8
# Chain configuration Juno
9
#
10
11
[[chains]]
12
id = 'juno-1'
13
rpc_addr = 'http://127.0.0.1:26657'
14
grpc_addr = 'http://127.0.0.1:29090'
15
websocket_addr = 'ws://127.0.0.1:26657/websocket'
16
17
rpc_timeout = '20s'
18
account_prefix = 'juno'
19
key_name = 'juno-relayer'
20
store_prefix = 'ibc'
21
max_msg_num=15
22
max_gas = 1000000
23
gas_price = { price = 0.001, denom = 'ujuno' }
24
clock_drift = '5s'
25
trusting_period = '14days'
26
trust_threshold = { numerator = '1', denominator = '3'}
27
28
[chains.packet_filter]
29
policy = 'allow'
30
list = [
31
['transfer', 'channel-0'],
32
['transfer', 'channel-1'],
33
['transfer', 'channel-5'],
34
]
35
36
37
#
38
# Chain configureation Osmosis
39
#
40
41
[[chains]]
42
id = 'osmosis-1'
43
44
# API access to Osmosis node with indexing
45
rpc_addr = 'http://127.0.0.1:36657'
46
grpc_addr = 'http://127.0.0.1:39090'
47
websocket_addr = 'ws://127.0.0.1:36657/websocket'
48
49
rpc_timeout = '20s'
50
account_prefix = 'osmo'
51
key_name = 'osmo-relayer'
52
store_prefix = 'ibc'
53
max_gas = 1000000
54
gas_price = { price = 0.000, denom = 'uosmo' }
55
clock_drift = '5s'
56
trusting_period = '7days'
57
trust_threshold = { numerator = '1', denominator = '3' }
58
59
[chains.packet_filter]
60
policy = 'allow'
61
list = [
62
['transfer', 'channel-42'],
63
]
64
65
#
66
# Chain configuration Cosmos
67
#
68
69
[[chains]]
70
id = 'cosmoshub-4'
71
72
# API access to Cosmos node with indexing
73
rpc_addr = 'http://127.0.0.1:46657'
74
grpc_addr = 'http://127.0.0.1:49090'
75
websocket_addr = 'ws://127.0.0.1:46657/websocket'
76
77
rpc_timeout = '20s'
78
account_prefix = 'cosmos'
79
key_name = 'cosmos-relayer'
80
store_prefix = 'ibc'
81
max_msg_num=15
82
max_gas = 1000000
83
gas_price = { price = 0.0001, denom = 'uatom' }
84
clock_drift = '5s'
85
trusting_period = '14days'
86
trust_threshold = { numerator = '1', denominator = '3' }
87
88
[chains.packet_filter]
89
policy = 'allow'
90
list = [
91
['transfer', 'channel-207'],
92
]
93
94
#
95
# Chain configuration Sifchain
96
#
97
98
[[chains]]
99
id = 'sifchain-1'
100
101
# API access to Cosmos node with indexing
102
rpc_addr = 'http://127.0.0.1:56657'
103
grpc_addr = 'http://127.0.0.1:59090'
104
websocket_addr = 'ws://127.0.0.1:56657/websocket'
105
106
rpc_timeout = '20s'
107
account_prefix = 'sif'
108
key_name = 'sif-relayer'
109
store_prefix = 'ibc'
110
max_msg_num=15
111
max_gas = 10000000
112
gas_price = { price = 0.001, denom = 'rowan' }
113
clock_drift = '5s'
114
trusting_period = '14days'
115
trust_threshold = { numerator = '1', denominator = '3' }
116
117
[chains.packet_filter]
118
policy = 'allow'
119
list = [
120
['transfer', 'channel-14'],
121
]
Copied!
You can validate the configuration with following:
1
[email protected]:~$ bin/hermes -c .hermes/config.toml config validate
2
Success: "validation passed successfully"
Copied!

Setting up wallets

We do this by creating key configuration files that are imported to hermes. Here we go trhough Juno key setting, other chains are similar.
1
{
2
"name":"juno-relayer",
3
"type":"local",
4
"address":"junoxxx",
5
"pubkey":"{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"xxx\"}",
6
"mnemonic": "24 words seed"
7
}
Copied!
Next we will import this key configuration to hermes and shred the used json file. (Using chain_id juno-1.)
1
bin/hermes keys add juno-1 -f ./seed-juno.json
2
shred -u ./seed-juno.json
Copied!
If you want to make sure the keys got imported, you can check them with following command (smart thing to run it before shredding the json file):
1
bin/hermes keys list juno-1
Copied!

Testing the setup

Let's do a quick test to see things work properly.
1
bin/hermes start
Copied!
Once we see things load up correctly and there are no fatal errors, we can break out of hermes with ctrl-c.

Configuring systemd

Now we will setup hermes to be run by systemd, and to start automatically on reboots.
Create the following configuration to /etc/systemd/system/hermes.service
1
[Unit]
2
Description=Hermes IBC relayer
3
ConditionPathExists=/srv/hermes/hermes
4
After=network.target juno.service cosmos.service osmo.service
5
6
[Service]
7
Type=simple
8
User=hermes
9
WorkingDirectory=/srv/hermes
10
ExecStart=/srv/hermes/hermes start
11
Restart=always
12
RestartSec=2
13
14
[Install]
15
WantedBy=multi-user.target
Copied!
Then we well start hermes with the newly created service and enable it. Note that this step is done from your normal user account that has sudo privileges, so no longer as hermes.
1
sudo systemctl start hermes.service
2
sudo systemctl enable hermes.service
Copied!
Last modified 1d ago