Hermes Guide (v1.6.0)

Overview

Hermes is an open-source Rust implementation of a relayer for the Inter-Blockchain Communication protocol (IBC) released under the ibc-relayer-cli crate. It provides a CLI to relay packets between Cosmos SDK chains, exposes Prometheus metrics and offers a REST API.

This guide can help you set up, configure, operate and monitor Hermes to relay packets between two or more IBC-enabled chains.

About Hermes

An IBC relayer is an off-chain process responsible for relaying IBC datagrams between any two chains. The way it does so is by scanning chain states, building transactions based on these states, and submitting the transactions to the chains involved in the network.

The relayer is a central element in the IBC network architecture. This is because chain modules in this architecture are not directly sending messages to each other over networking infrastructure, but instead they create and store the data to be retrieved and used by a relayer to build the IBC datagrams.

We sometimes refer to Hermes as "IBC Relayer CLI", to make it clear that this is a relayer CLI (i.e., a binary) and distinguish it from the relayer core library (that is the crate called ibc-relayer).

Hermes is actively developed and maintained by Informal Systems in the informalsystems/hermes repository.

Note that Hermes is packaged as part of the ibc-relayer-cli crate and not the hermes crate, which is unrelated.

Where to go

• Glossary

  • This section provides some definitions of terms used throughout the guide.

• Quick start

  • This section helps you install Hermes.

• Tutorials

  • Prerequisites for local chains
    • Install Gaia and gm (Gaia Manager) for tutorials using local chains.
  • Two Local Chains
    • Start two local Cosmos Gaia chains that support the IBC protocol and learn the fundamentals of IBC.
  • More Local Chains
    • Learn how to relay on an arbitrary topology of more than two chains by using packet filters and to run multiple instances of Hermes.
  • Relaying in production
    • Learn how to set up, configure and run hermes on IBC-enabled chains in production.

• Advanced

  • Features
    • This section summarizes Hermes' features and includes a comparison between the Cosmos Go relayer and Hermes.
  • Troubleshooting
    • Learn the general guidelines regarding troubleshooting.

• Documentation

  • Configuration
    • This section includes everything you need to know to configure Hermes.
  • Telemetry
    • This section describes all Prometheus metrics and how to use them efficiently.
  • REST API
    • This section presents Hermes' REST API.
  • Commands Reference
    • This section describes the command line interface from which you can interact with Hermes.

• Educational resources

  • About IBC
    • The official IBC-Go documentation.
  • Cosmos network tutorial
    • Learn the basics of IBC in the official tutorial.
  • Connect IBC enabled chains with Hermes
    • Video demonstration of Hermes at Hackatom 2021.

• Useful links

  • Hermes FAQ Page
    • The official FAQ of Hermes.
  • Hermes GitHub repository
    • The official GitHub repository for Hermes.
  • IBC GitHub repository
    • The official repository for the Inter-blockchain protocol (IBC).
  • IBC Protocol
    • The official IBC protocol page.

Contact

• Request a new feature via the feature request issue template;
• Consult the list of reported issues and search by relevant keywords to see if you're dealing with a known problem;
• We would be grateful if you can submit a bug report discussing any problem you find, and from there on we can look at the problem together;
• Reach Hermes developers and other relayer operators in the #hermes channel on the IBC Gang Discord.

Lastly, for general questions, you can reach us at hello@informal.systems, or on Twitter @informalinc.

Disclaimer As with all software offered by Informal Systems, Hermes is offered on an “as is” basis and you use at your own risk. Informal makes no warranties of any kind, express or implied, relating to Hermes, including no warranties of a “bug-free” nature.