Configure Hermes
In order to run Hermes, you will need to have a configuration file.
The format supported for the configuration file is TOML.
By default, Hermes expects the configuration file to be located at $HOME/.hermes/config.toml
.
This can be overridden by supplying the --config
flag when invoking hermes
, before the
name of the command to run, e.g. hermes --config my_config.toml query connection channels --chain ibc-1 --connection connection-1
.
The current version of Hermes does not support managing the configuration file programmatically. You will need to use a text editor to create the file and add content to it.
hermes [--config CONFIG_FILE] COMMAND
Table of contents
- Configuration
- Adding Private Keys
- Connecting via TLS
- Configuring Support for Interchain Accounts
- Configuring Support for Consumer Chains that Utilize Cross-Chain Validation
- Connecting to a full node protected by HTTP Basic Authentication
- Configuring Support for Wasm Relaying
Configuration
Automatically Generating A Config File
The simplest way to configure Hermes for a given chain is by running the command
hermes config auto --output ~/<OUTPUT_PATH>/config.toml --chain <CHAIN_1> <CHAIN_2> --chain
This will generate a config.toml
file for some specified chains. Note, however, that the configuration is generated by pulling the chain data from the Cosmos chain registry. The specified chain(s) must exist in the registry for the command to work. Check out this section of the Hermes commands reference to find more information on the config auto
command.
Tips for Manually Configuring Hermes
For relaying use-cases that require some more bespoke configuration, you'll have to manually edit the config.toml
file. The following are some rules of thumb to follow when manually configuring Hermes.
The configuration file must have one global
section, and one chains
section for each chain.
Note: As of 0.6.0, the Hermes configuration file is self-documented. Please read the configuration file
config.toml
itself for the most up-to-date documentation of parameters.
By default, Hermes will relay on all channels available between all the configured chains. In this way, every configured chain will act as a source (in the sense that Hermes listens for events) and as a destination (to relay packets that others chains have sent).
For example, if there are only two chains configured, then Hermes will only relay packets between those two, i.e. the two chains will serve as a source for each other, and likewise as a destination for each other's relevant events. Hermes will ignore all events that pertain to chains which are unknown (i.e. not present in config.toml).
To restrict relaying on specific channels, or uni-directionally, you can use packet filtering policies.
Check out the example config.toml file in the Hermes repo to see how the different parameters can be configured.
Adding Private Keys
For each chain configured you need to add a private key for that chain in order to submit transactions, please refer to the Keys sections in order to learn how to add the private keys that are used by Hermes.
Connecting via TLS
Hermes supports connection via TLS for use-cases such as connecting from behind
a proxy or a load balancer. In order to enable this, you'll want to set the
rpc_addr
, grpc_addr
, or event_source
parameters to specify a TLS
connection via HTTPS using the following scheme (note that the port number 443
is just used for example):
rpc_addr = 'https://domain.com:443'
grpc_addr = 'https://domain.com:443'
event_source = { mode = 'push', url = 'wss://domain.com:443/websocket', batch_delay = '500ms' }
Configuring Support for Interchain Accounts
As of version 0.13.0, Hermes supports relaying on Interchain Accounts channels.
If the packet_filter
option in the chain configuration is disabled, then
Hermes will relay on all existing and future channels, including ICA channels.
There are two kinds of ICA channels:
- The host channels, whose port is
icahost
- The controller channels, whose port starts with
icacontroller-
followed by the owner account address. See the spec for more details.
If you wish to only relay on a few specific standard channels (here channel-0
and channel-1
),
but also relay on all ICA channels, you can specify the following packet filter:
Note the use of wildcards in the port and channel identifiers (
['ica*', '*']
) to match over all the possible ICA ports.
[chains.packet_filter]
policy = 'allow'
list = [
['ica*', '*'], # allow relaying on all channels whose port starts with `ica`
['transfer', 'channel-0'],
['transfer', 'channel-1'],
# Add any other port/channel pairs you wish to relay on
]
If you wish to relay on all channels but not on ICA channels, you can use the following packet filter configuration:
[chains.packet_filter]
policy = 'deny'
list = [
['ica*', '*'], # deny relaying on all channels whose port starts with `ica`
]
Configuring Support for Consumer Chains that Utilize Cross-Chain Validation
As of version 1.4.1, Hermes supports relaying for consumer chains that utilize cross-chain validation (CCV).
Note: A consumer chain is essentially a regular Cosmos-SDK based chain that uses the interchain security module to achieve economic security by stake deposited on a provider chain instead of on the consumer chain itself. Consumer chains are bound to their provider chains by the provider's validator set. By being bound together in this way, consumer chains inherit the economic security guarantees of the provider chain.
You can read more about consumer chains, and Interchain Security more generally, at https://cosmos.github.io/interchain-security.
If you are configuring Hermes in order to relay for a consumer chain, set ccv_consumer_chain = true
under its [[chains]]
section in the config.toml
file.
By default, this option is set to false
. It should ONLY be toggled on for CCV consumer chains, NOT for sovereign chains.
This parameter is required because consumer chains do not utilize the same staking module as sovereign chains.
Consumer chains must query a different gRPC endpoint in order to fetch the relevant ccvconsumer
parameters that Hermes
needs in order to relay on behalf of consumer chains.
Connecting to a full node protected by HTTP Basic Authentication
To connect to a full node protected by HTTP Basic Authentication,
specify the username and password in the rpc_addr
, grpc_addr
and event_source
settings
under the chain configuration in config.toml
.
Here is an example with username hello
and password world
, assuming the RPC, WebSocket and gRPC servers
listen on domain mydomain.com
with TLS enabled (HTTPS/WSS).
[[chains]]
id = 'my-chain-0'
# ...
rpc_addr = 'https://hello:world@mydomain.com:26657'
grpc_addr = 'https://hello:world@mydomain.com:9090'
event_source = { mode = 'push', url = 'wss://hello:world@mydomain.com:26657/websocket', batch_delay = '500ms' }
# ...
Caution: The "Basic" authentication scheme sends the credentials encoded but not encrypted. This would be completely insecure unless the exchange was over a secure connection (HTTPS/TLS).
Configuring Support for Wasm Relaying
Hermes supports the relaying of wasm messages natively. This is facilitated by configuring
Hermes to use pull-based relaying by polling for IBC events via the /block_results
RPC endpoint. Set
the event_source
parameter to pull mode in config.toml
like so:
# When specified like this, Hermes defaults to a poll interval of 1 second
event_source = { mode = 'pull' }
The default interval at which Hermes polls the RPC endpoint is 1 second. If you need to change the interval, you can specify it like so:
event_source = { mode = 'pull', interval = '2s' }
The pull model of relaying is in contrast with Hermes' default push model, where IBC events are received over WebSocket.
Note: This mode should only be used in situations where Hermes misses events that it should be receiving, such as when relaying for CosmWasm-enabled blockchains which emit IBC events without the
message
attribute. Without this attribute, the WebSocket is not able to catch these events to stream to Hermes, so the/block_results
RPC endpoint must be used instead.