Description of the parameters

This page provides a full example of a configuration file with two chains configured:

NOTE: Visit the Relaying section to learn more about Hermes' modes.

# This is an example configuration for Hermes. It is meant to be
# used as a reference, _NOT_ for configuring a production relayer. 
# If you're looking to configure a production relayer for some chains, 
# try using the `hermes config auto` command to generate a config 
# file that serves as the starting point for configuring Hermes.

# The global section has parameters that apply globally to the relayer operation.
[global]

# Specify the verbosity for the relayer logging output. Default: 'info'
# Valid options are 'error', 'warn', 'info', 'debug', 'trace'.
log_level = 'debug'


# Specify the mode to be used by the relayer. [Required]
[mode]

# Specify the client mode.
[mode.clients]

# Whether or not to enable the client workers. [Required]
enabled = true

# Whether or not to enable periodic refresh of clients. [Default: true]
# This feature only applies to clients that underlie an open channel.
# For Tendermint clients, the frequency at which Hermes refreshes them is 2/3 of their
# trusting period (e.g., refresh every ~9 days if the trusting period is 14 days).
# Note: Even if this is disabled, clients will be refreshed automatically if
#      there is activity on a connection or channel they are involved with.
refresh = true

# Whether or not to enable misbehaviour detection for clients. [Default: true]
misbehaviour = true

# Specify the connections mode.
[mode.connections]

# Whether or not to enable the connection workers for handshake completion. [Required]
enabled = true

# Specify the channels mode.
[mode.channels]

# Whether or not to enable the channel workers for handshake completion. [Required]
enabled = true

# Specify the packets mode.
[mode.packets]

# Whether or not to enable the packet workers. [Required]
enabled = true

# Parametrize the periodic packet clearing feature.
# Interval (in number of blocks) at which pending packets
# should be periodically cleared. A value of '0' will disable
# periodic packet clearing. [Default: 100]
clear_interval = 100

# Whether or not to clear packets on start. [Default: true]
clear_on_start = true

# Set the maximum number of packets to clear each time packet clearing is triggered.
# [Default: 50]
#clear_limit = 50

# Toggle the transaction confirmation mechanism.
# The tx confirmation mechanism periodically queries the `/tx_search` RPC
# endpoint to check that previously-submitted transactions
# (to any chain in this config file) have been successfully delivered.
# If they have not been, and `clear_interval = 0`, then those packets are
# queued up for re-submission.
# If set to `false`, the following telemetry metrics will be disabled:
# `acknowledgment_packets_confirmed`, `receive_packets_confirmed` and `timeout_packets_confirmed`.
# [Default: false]
tx_confirmation = false

# Auto register the counterparty payee on a destination chain to
# the relayer's address on the source chain. This can be used
# for simple configuration of the relayer to receive fees for
# relaying RecvPacket on fee-enabled channels.
# For more complex configuration, turn this off and use the CLI
# to manually register the payee addresses.
# [Default: false]
auto_register_counterparty_payee = false

# Set the maximum size for the memo field in ICS20 packets.
# If the size of the memo field is bigger than the configured
# one, the packet will not be relayed.
# The filter can be disabled by setting `enabled = false`.
# [Default: "32KiB"]
#ics20_max_memo_size = { enabled = true, size = "32KiB" }

# Set the maximum size for the receiver field in ICS20 packets.
# If the size of the receiver field is bigger than the configured
# one, the packet will not be relayed.
# The filter can be disabled by setting `enabled = false`.
# [Default: "2KiB"]
#ics20_max_receiver_size = { enabled = true, size = "2KiB" }

# The REST section defines parameters for Hermes' built-in RESTful API.
# https://hermes.informal.systems/rest.html
[rest]

# Whether or not to enable the REST service. Default: false
enabled = false

# Specify the IPv4/6 host over which the built-in HTTP server will serve the RESTful
# API requests. Default: 127.0.0.1
host = '127.0.0.1'

# Specify the port over which the built-in HTTP server will serve the restful API
# requests. Default: 3000
port = 3000


# The telemetry section defines parameters for Hermes' built-in telemetry capabilities.
# https://hermes.informal.systems/telemetry.html
[telemetry]

# Whether or not to enable the telemetry service. Default: false
enabled = false

# Specify the IPv4/6 host over which the built-in HTTP server will serve the metrics
# gathered by the telemetry service. Default: 127.0.0.1
host = '127.0.0.1'

# Specify the port over which the built-in HTTP server will serve the metrics gathered
# by the telemetry service. Default: 3001
port = 3001

[telemetry.buckets]
# Specify the range of the 10 histogram buckets in ms for the `tx_latency_submitted` metric.
# Default: { start = 500, end = 10000, buckets = 10 }
# The default will give the following buckets:
# [500, 2450, 4400, 6350, 8300, 10250, 12200, 14150, 16100, 18050, 20000]
# latency_submitted = { start = 500, end = 20000, buckets = 10 }

# Specify the range of the 10 histogram buckets in ms for the `tx_latency_confirmed` metric.
# Default: { start = 1000, end = 20000, buckets = 10 }
# The default will give the following buckets:
# [1000, 3900, 6800, 9700, 12600, 15500, 18400, 21300, 24200, 27100, 30000]
# latency_confirmed = { start = 1000, end = 30000, buckets = 10 }

# The tracing server section defines parameters for Hermes' server allowing updates to the tracing directives.
#
# https://hermes.informal.systems/advanced/troubleshooting/log-level.html#overriding-the-tracing-filter-during-runtime
[tracing_server]
# Whether or not to enable the tracing server. Default: false
enabled = false

# Specify the port over which the built-in TCP server will serve the directives. Default: 5555
port = 5555

# A chains section includes parameters related to a chain and the full node to which
# the relayer can send transactions and queries.
[[chains]]

# Specify the chain ID. Required
id = 'ibc-0'

# Specify the chain type, currently only `CosmosSdk` is supported.
# Default: CosmosSdk
type = "CosmosSdk"

# Whether or not this is a CCV consumer chain. Default: false
# Only specify true for CCV consumer chain, but NOT for sovereign chains.
ccv_consumer_chain = false

# Specify the RPC address and port where the chain RPC server listens on. Required
rpc_addr = 'http://127.0.0.1:26657'

# Specify the GRPC address and port where the chain GRPC server listens on. Required
grpc_addr = 'http://127.0.0.1:9090'

# The type of event source to use for getting events from the chain.
#
# This setting can take two types of values, as an inline table:
# 
# a) Push: for receiving IBC events over WebSocket.
#
#      `{ mode = 'push', url = 'ws://127.0.0.1:26657/websocket', batch_delay = '500ms' }`
#
#    where
#
#    - `url` is the WebSocket URL to connect to. Required
#    - `batch_delay` is the delay until event batch is
#      emitted in the absence of NewBlock event. Default: 500ms
#      Lower values will result in faster event processing, improving the latency of Hermes,
#      but may split the events into more batches than necessary, requiring more client updates
#      to be submitted, yielding higher costs. Higher values will result in slower event
#      processing, increasing the latency of Hermes, but are more likely to batch events together.
#      The default value provides good latency while minimizing the number of client updates needed.

# b) Pull: for polling for IBC events via the `/block_results` RPC endpoint.
#
#     `{ mode = 'pull', interval = '1s', max_retries = 4 }`
#
#    where
#
#    - `interval` is the interval at which to poll for blocks. Default: 1s
#    - `max_retries` is the maximum number of retries to collect events for each block. Default: 4
#
#    This mode should only be used in situations where Hermes misses events that it should be
#    receiving, such as when relaying for CosmWasm-enabled chains which emit IBC events without
#    the `message` attribute. Without this attribute, the WebSocket is not able to catch these
#    events, so the `/block_results` RPC must be used instead.
#
event_source = { mode = 'push', url = 'ws://127.0.0.1:26657/websocket', batch_delay = '500ms' }

# Specify the maximum amount of time (duration) that the RPC requests should
# take before timing out. Default: 10s (10 seconds)
# Note: Hermes uses this parameter _only_ in `start` mode; for all other CLIs,
# Hermes uses a large preconfigured timeout (on the order of minutes).
rpc_timeout = '10s'

# Experimental: Whether or not the full node is trusted.
#
# If not trusted, Hermes will verify headers included in the `ClientUpdate` message using the light client.
#
# Note: If the full node is configured as trusted then, in addition to headers not being verified,
#       the verification traces will not be provided.
#       This may cause failure in client updates after significant change in validator sets.
#
# Default: false
trusted_node = false

# Specify the prefix used by the chain. Required
account_prefix = 'cosmos'

# Specify the name of the private key to use for signing transactions. Required
# See the Adding Keys chapter for more information about managing signing keys:
#   https://hermes.informal.systems/documentation/commands/keys/index.html#adding-keys
key_name = 'testkey'

# Specify the folder used to store the keys. Optional
# If this is not specified then the hermes home folder is used.
# key_store_folder = '$HOME/.hermes/keys'

# Specify the address type which determines:
# 1) address derivation;
# 2) how to retrieve and decode accounts and pubkeys;
# 3) the message signing method.
# The current configuration options are for Cosmos SDK and Ethermint.
#
# Example configuration for chains based on Ethermint library:
#
# address_type = { derivation = 'ethermint', proto_type = { pk_type = '/ethermint.crypto.v1.ethsecp256k1.PubKey' } }
#
# Default: { derivation = 'cosmos' }, i.e. address derivation as in Cosmos SDK.
# Warning: This is an advanced feature! Modify with caution.
address_type = { derivation = 'cosmos' }

# Specify the store prefix used by the on-chain IBC modules. Required
# Recommended value for Cosmos SDK: 'ibc'
store_prefix = 'ibc'

# Gas Parameters
# 
# The term 'gas' is used to denote the amount of computation needed to execute
# and validate a transaction on-chain. It can be thought of as fuel that gets 
# spent in order to power the on-chain execution of a transaction.
#
# Hermes attempts to simulate how much gas a transaction will expend on its 
# target chain. From that, it calculates the cost of that gas by multiplying the
# amount of estimated gas by the `gas_multiplier` and the `gas_price`
# (estimated gas * `gas_multiplier` * `gas_price`) in order to compute the 
# total fee to be deducted from the relayer's wallet.
# 
# The `simulate_tx` operation does not always correctly estimate the appropriate
# amount of gas that a transaction requires. In those cases when the operation 
# fails, Hermes will attempt to submit the transaction using the specified 
# `default_gas` and `max_gas` parameters. In the case that a transaction would 
# require more than `max_gas`, it doesn't get submitted and a 
# `TxSimulateGasEstimateExceeded` error is returned.

# Specify the default amount of gas to be used in case the tx simulation fails,
# and Hermes cannot estimate the amount of gas needed.
# Default: 100 000
default_gas = 100000

# Specify the maximum amount of gas to be used as the gas limit for a transaction.
# If `default_gas` is unspecified, then `max_gas` will be used as `default_gas`.
# Default: 400 000
max_gas = 4000000

# Specify the price per gas used of the fee to submit a transaction and
# the denomination of the fee. 
# 
# The specified gas price should always be greater or equal to the `min-gas-price`
# configured on the chain. This is to ensure that at least some minimal price is 
# paid for each unit of gas per transaction.
# 
# Required
gas_price = { price = 0.025, denom = 'stake' }

# Multiply this amount with the gas estimate, used to compute the fee
# and account for potential estimation error.
#
# The purpose of multiplying by `gas_multiplier` is to provide a bit of a buffer
# to catch some of the cases when the gas estimation calculation is on the low
# end. 
# 
# Example: With this setting set to 1.1, then if the estimated gas
# is 80_000, then gas used to compute the fee will be adjusted to
# 80_000 * 1.1 = 88_000.
#
# Default: 1.1, ie. the gas is increased by 10%
# Minimum value: 1.0
gas_multiplier = 1.1

# Query the current gas price from the chain instead of using the static `gas_price` from the config.
# Useful for chains which have [EIP-1559][eip]-like dynamic gas price. 
#
# At the moment, only chains which support the `osmosis.txfees.v1beta1.Query/GetEipBaseFee`
# query or have enabled Skip's `x/feemarket` module https://github.com/skip-mev/feemarket
# can be used with dynamic gas price enabled.
#
# See this page in the Hermes guide for more information:
# https://hermes.informal.systems/documentation/configuration/dynamic-gas-fees.html
# 
# Default: { enabled = false, multiplier = 1.1, max = 0.6 }
dynamic_gas_price = { enabled = false, multiplier = 1.1, max = 0.6 }

# Specify how many IBC messages at most to include in a single transaction.
# Default: 30
max_msg_num = 30

# Specify the maximum size, in bytes, of each transaction that Hermes will submit.
# Default: 2097152 (2 MiB)
max_tx_size = 2097152

# How many packets to fetch at once from the chain when clearing packets.
# Default: 50
query_packets_chunk_size = 50

# Specify the maximum amount of time to tolerate a clock drift.
# The clock drift parameter defines how much new (untrusted) header's time
# can drift into the future. Default: 5s
clock_drift = '5s'

# Specify the fallback value for the maximum time per block for this chain.
# The block time together with the clock drift are added to the source drift to estimate
# the maximum clock drift when creating a client on this chain. Default: 30s
# When validating the configuration, Hermes will query the /genesis RPC endpoint in order
# to retrieve the `max_expected_time_per_block` and use it as the `max_block_time`.
# If the query fails, the configured `max_block_time` is used instead.
# For cosmos-SDK chains a good approximation is `timeout_propose` + `timeout_commit`
# Note: This MUST be the same as the `max_expected_time_per_block` genesis parameter for Tendermint chains.
max_block_time = '30s'

# Specify the amount of time to be used as the light client trusting period.
# It should be significantly less than the unbonding period
# (e.g. unbonding period = 3 weeks, trusting period = 2 weeks).
#
# Default: 2/3 of the `unbonding period` for Cosmos SDK chains
trusting_period = '14days'

# The rate at which to refresh the client referencing this chain,
# expressed as a fraction of the trusting period.
#
# Default: 1/3 (ie. three times per trusting period)
client_refresh_rate = '1/3'

# Specify the trust threshold for the light client, ie. the minimum fraction of validators
# which must overlap across two blocks during light client verification.
#
# Warning: This is an advanced feature! Modify with caution.
#
# Default: 2/3
trust_threshold = '2/3'

# Specify a string that Hermes will use as a memo for each transaction it submits
# to this chain. The string is limited to 50 characters. Default: '' (empty).
# Note: Hermes will append to the string defined here additional
# operational debugging information, e.g., relayer build version.
memo_prefix = ''

# If this is set to a string, it will overwrite the memo used by Hermes for each transaction
# it submits to this chain.
# Default: not set.
# This is used for chains which have a very small character limit for the memo,
# and the additional information appended by Hermes would overflow that limit.
# memo_overwrite = ''

# This section specifies the filters for policy based relaying.
#
# Default: no policy / filters, allow all packets on all channels.
#
# Only packet filtering based on channel identifier can be specified.
# A channel filter has two fields:
# 1. `policy` - one of two types are supported:
#       - 'allow': permit relaying _only on_ the port/channel id in the list below,
#       - 'deny': permit relaying on any channel _except for_ the list below.
# 2. `list` - the list of channels specified by the port and channel identifiers.
#             Optionally, each element may also contains wildcards, for eg. 'ica*'
#             to match all identifiers starting with 'ica' or '*' to match all identifiers.
#
# Example configuration of a channel filter, only allowing packet relaying on
# channel with port ID 'transfer' and channel ID 'channel-0', as well as on
# all ICA channels.
#
# [chains.packet_filter]
# policy = 'allow'
# list = [
#   ['ica*', '*'],
#   ['transfer', 'channel-0'],
# ]

# This section specifies the filters for incentivized packet relaying.
# Default: no filters, will relay all packets even if they
# are not incentivized.
#
# It is possible to specify the channel or use wildcards for the
# channels.
# The only fee which can be parametrized is the `recv_fee`.
#
# Example configuration of a filter which will only relay incentivized
# packets, with no regards for channel and amount.
#
# [chains.packet_filter.min_fees.'*']
# recv = [ { amount = 0 } ]
#
# Example configuration of a filter which will only relay packets if they are
# from the channel 'channel-0', and they have a `recv_fee` of at least 20 stake
# or 10 uatom.
#
# [chains.packet_filter.min_fees.'channel-0']
# recv = [ { amount = 20, denom = 'stake' }, { amount = 10, denom = 'uatom' } ]

# Specify that the transaction fees should be paid from this fee granter's account.
# Optional. If unspecified (the default behavior), then no fee granter is used, and
# the account specified in `key_name` will pay the tx fees for all transactions
# submitted to this chain.
# fee_granter = ''

# Specify the CometBFT compatibility mode to use.
# The following behaviours are applied whether the `compat_mode` is configured or not:
#   * compat_mode is specified and the version queried from /status is the same as the one configured: Use that version without log output
#   * compat_mode is specified but the version queried from /status differs: The CompatMode configured is used, but a warning log is outputted
#   * compat_mode is not specified but /status returns a correct version: The CompatMode retrieved from the endpoint is used
#   * compat_mode is not specified and /status does not return a valid version: Hermes stops and outputs an error informing the user a compat_mode needs to be configured
# Possible values: [`0.34`, `0.37`]
# compat_mode = '0.34'

# Specify the a clear interval for the chain.
# This will override the global clear interval for this chain only, allowing different intervals for each chain.
# clear_interval = 50

# Specify packet sequences which should not be cleared, per channel.
#
# For each channel, specify a list of sequences which should not be cleared. Acceptable value
# include range of sequences with separator "-", eg.
#
#   [chains.excluded_sequences]
#   channel-0 = [1, 2, "3-7", 9, 11],
#   channel-1 = [4, 5, 6],
#
# Default: No filter
# excluded_sequences = {}

# Enable or disable relaying of ICS31 Cross Chain Query packets.
# If this configuration is set to false, Hermes will skip ICS31
# Cross Chain Query packets.
#
# Default: true
# allow_ccq = true

[[chains]]
id = 'ibc-1'
rpc_addr = 'http://127.0.0.1:26557'
grpc_addr = 'http://127.0.0.1:9091'
event_source = { mode = 'push', url = 'ws://127.0.0.1:26557/websocket', batch_delay = '500ms' }
rpc_timeout = '10s'
trusted_node = false
account_prefix = 'cosmos'
key_name = 'testkey'
store_prefix = 'ibc'
default_gas = 100000
max_gas = 4000000
gas_price = { price = 0.025, denom = 'stake' }
gas_multiplier = 1.1
max_msg_num = 30
max_tx_size = 2097152
clock_drift = '5s'
max_block_time = '30s'
trusting_period = '14days'
trust_threshold = '2/3'
address_type = { derivation = 'cosmos' }