Skip to content

Latest commit

 

History

History
3533 lines (2683 loc) · 161 KB

CHANGELOG.md

File metadata and controls

3533 lines (2683 loc) · 161 KB
Raw

CHANGELOG

v1.8.2

March 12th, 2024

This release fixes the two following bugs and improves the connection and channel handshake retry mechanism:

  • Fix erroneous warnings for incompatible version of IBC-Go during health checks, ensuring accurate compatibility reporting
  • Fix a bug in the clear packets command which caused packet clearing to fail with an "counterparty channel not found" error

BUG FIXES

  • Relayer CLI
    • Correctly use the counterparty channel and port IDs when clearing the packets from the destination chain to the source chain in the packet clear command (#3889)
  • Relayer
    • Fix parsing of IBC-Go version in health check and improve health check reporting (#3880)

FEATURES

IMPROVEMENTS

  • Relayer
    • Change connection and channel handshake retry strategy to retry at most 10 times (5 times per block max) (#3864)

v1.8.1

March 7th, 2024

This v1.8.1 release brings better reliability when relaying, more enhanced configuration and improved monitoring.

Reliability has been improved:

  • It is now possible to relay ICS-04 packets with non-UTF-8 payloads
  • Packet sequences are now verified for ordered channels before trying to relay

Additional per-chain configurations have been added:

  • excluded_sequences used to skip problematic packets when clearing
  • memo_overwrite allowing users to overwrite the relayer memo when chains have a strict limit for the size of the memo.

Monitoring issues improvements:

  • A new metric simulate_errors which counts the number of failed simulated transactions
  • Out of gas error diagnostic gives more information and a dedicated entry to the guide has been added
  • Failed gas simulation will not be considered as unrecoverable for legacy chains.
  • The compatibility check during the health-check has been improved will assess more correctly the versions for Ibc-Go and Cosmos SDK

Special thanks to our contributors for their valuable additions to this release:

  • Sergey (@freak12techno) for adding the simulate_errors metric ([#3845])
  • Martin Dyring-Andersen (@mdyring) for adding recovery from failed gas simulation for legacy chains ([#3792])

BUG FIXES

  • Allow relaying ICS-04 packets with non-UTF-8 payloads (#3770) Hermes does not assume anymore that an ICS-04 packet data is valid UTF-8, by using the packet_data_hex attribute when assembling a packet from events, instead of the deprecated packet_data attribute. Relying on the packet_data attribute enforces a UTF-8 encoded payload (eg. JSON), disallowing eg. Protobuf-encoded payloads. The packet_data attribute has been deprecated in favor of packet_data_hex since IBC-Go v1.0.0.
  • Improve reliability of compatibility check and fix parsing of expected modules versions (#3831)

FEATURES

  • Add a per-chain configuration excluded_sequences allowing users to specify a list of packet sequences which will not be cleared. This configuration has no impact on standard packet relaying. (#3754)
  • Add a per-chain configuration memo_overwrite allowing users to overwrite the relayer memo used for each transaction (#3811)
  • Added a new Prometheus metric simulate_errors for tracking when a transaction simulation fails, with the following labels: (#3845)

    • recoverable (can the execution continue if this happened?)

    • account (account from which the tx was sent)

    • error_description (description of the error)

      # HELP simulate_errors_total Number of errors observed by Hermes when simulating a Tx
# TYPE simulate_errors_total counter
simulate_errors_total{account="osmo17ndx5qfku28ymxgmq6zq4a6d02dvpfjjul0hyh",error_description="Unknown error",recoverable="false",service_name="unknown_service",otel_scope_name="hermes",otel_scope_version=""} 4

IMPROVEMENTS

  • Use the consensus state at client latest height in status CLI (#3814)
  • Add syncing check for gRPC node (#3814)
  • Improve the log diagnostic when an out of gas error is thrown. And a new entry related to gas error has been added to the Hermes guide. (#3530)
  • Improve resilience when relaying on ordered channels. When relaying packets on an ordered channel, Hermes will now attempt to detect whether the next message to send has the sequence number expected on that channel. If there is a mismatch, then Hermes will trigger a packet clear on the channel to unblock it before resuming operations on that channel. (#3540)
  • Recover from gas simulation failures on legacy chains. (#3792)

v1.8.0

January 23rd, 2024

This v1.8.0 release introduces new features and improvements to Hermes.

One key feature is that Hermes is now compatible with both the legacy UpgradeProposal and the newer MsgIbcSoftwareUpgrade message when upgrading a chain. This allows Hermes to be compatible with ibc-go v8.0.0. The compatibility check that Hermes performs on startup has been updated to reflect this.

Additional configuration settings have been added:

  • The new global settings ics20_max_memo_size and ics20_max_receiver_size allow users to specify a limit for the size of the memo and receiver fields for ICS20 packets. Any packet with either field having a size exceeding the configured values will not be relayed.
  • The new per-chain setting query_packets_chunk_size allows users to specify how many packets are queried at once from the chain when clearing pending packets. This is useful to tweak when there are many large pending packets and the RPC endpoints times out or refuses to answer the pending packets query.
  • The new per-chain setting client_refresh_rate can be use to specify how often the clients referencing this chain should be refreshed. The rate is expressed as a fraction of the trusting period.
  • The new per-chain setting dynamic_gas_price can be enabled to have the relayer query for and use a dynamic gas price instead of using the static gas_price specified in the config. This should only be used for chains which have a EIP-1559-like fee market enabled and support the osmosis.txfees.v1beta1.Query/GetEipBaseFee gRPC query.

Telemetry now features new metrics:

  • Monitoring the ICS20 packets filtered due to the memo and/or receiver field size exceeding the configured limits.
  • Monitoring the distribution of dynamic gas fees queried from the chain, if enabled.

BREAKING CHANGES

  • Bump MSRV to 1.71 (#3688)

FEATURES

  • Relayer

    • Use legacy UpgradeProposal or newer MsgIbcSoftwareUpgrade message when upgrading a chain depending on whether the chain is running IBC-Go v8 or older. (#3696)

    • Add a new per-chain configuration table dynamic_gas_price which enables querying the current gas price from the chain instead of the static gas_price, when the chain has EIP-1559-like dynamic gas price. The new configuration setting can be configured per-chain as follows:

      dynamic_gas_price = { enabled = true, multiplier = 1.1, max = 0.6 }

      At the moment, only chains which support the osmosis.txfees.v1beta1.Query/GetEipBaseFee query can be used with dynamic gas price enabled. (#3738)

    • Add two new packet configurations:

      • ics20_max_memo_size which filters ICS20 packets with memo field bigger than the configured value
      • ics20_max_receiver_size which filters ICS20 packets with receiver field bigger than the configured value (#3766)

    • Add a client_refresh_rate setting to specify the rate at which to refresh clients referencing this chain, relative to its trusting period. (#3402)

    • Add a --packet-sequences flag to the clear packets, tx packet-recv, and tx packet-ack commands. When this flag is specified, these commands will only clear the packets with the specified sequence numbers on the given chain. If not provided, all pending packets will be cleared on both chains, as before. (#3672)

      This flag takes either a single sequence number or a range of sequences numbers. Each element of the comma-separated list must be either a single sequence number or a range of sequence numbers.

      Examples:

      • 10 will clear a single packet with sequence number 10
      • 1,2,3 will clear packets with sequence numbers 1, 2, 3
      • 1..5 will clear packets with sequence numbers 1, 2, 3, 4, 5
      • ..5 will clear packets with sequence numbers 1, 2, 3, 4, 5
      • 5.. will clear packets with sequence numbers greater than or equal to 5
      • ..5,10..20,25,30.. will clear packets with sequence numbers 1, 2, 3, 4, 5, 10, 11, ..., 20, 25, 30, 31, ...
      • ..5,10..20,25,30.. will clear packets with sequence numbers 1, 2, 3, 4, 5, 10, 11, ..., 20, 25, 30, 31, ...

    • Add a --gov-account option to hermes tx upgrade-chain to specify the authority account used to sign upgrade proposal for chains running IBC-Go v8+. (#3696)

    • Add a query_packets_chunk_size config option and a --query-packets-chunk-size flag to the clear packets CLI to configure how many packets to query at once from the chain when clearing pending packets. Lower this setting if one or more of packets you are trying to clear are huge and make the packet query time out or fail. (#3743)

  • Telemetry & Metrics
    • Add three metrics related to EIP gas price:
    • dynamic_gas_queried_fees contains data on the queried values before applying any filter
    • dynamic_gas_queried_success_fees contains data on the queried values if the query was successful and before applying any filter
    • dynamic_gas_paid_fees contains data on the queried values after applying the max filter (#3738)
    • Add a new metric filtered_packets which counts the number of packets filtered due to having a memo or receiver field too big (#3794)
  • Integration Test Framework
    • Add a test for asynchronous Interchain Query relaying (#3455)
    • Add an ICA test to assert a channel correctly closes after a packet time-outs (#3778)

IMPROVEMENTS

  • Relayer CLI
    • Update compatibility check to allow IBC-Go 4.1.1 to 8.x and SDK 0.45.x to 0.50.x. (#3745)

v1.7.4

December 15th, 2023

Special thanks to Yun Yeo (@beer-1) for his contributions (#3697 and #3703).

This release improves the monitoring of Hermes instances by fixing the broadcast_errors metric so that it correctly batches the same errors together. It also improves the metrics backlog_* by updating them whenever Hermes queries pending packets.

This release also improves the reliability of the idle worker clean-up and fixes a bug within the evidence command which would sometimes prevent the misbehaviour evidence from being reported.

BUG FIXES

  • Relayer CLI
    • Fix a bug in the evidence command which would sometimes prevent the detected misbehaviour evidence from being submitted, instead erroring out with a validator set hash mismatch. (#3697)
  • Relayer Library
    • Avoid retrieving a worker which is being removed by the idle worker clean-up process. (#3703)
  • Telemetry & Metrics
    • Fix the issue where broadcast_errors metric would not correctly batch the same errors together.(#3720)
    • Update the values of backlog metrics when clearing packets. Change the backlog_oldest_timestamp to backlog_latest_update_timestamp which shows the last time the backlog metrics have been updated. (#3723)

v1.7.3

November 29th, 2023

This release improves the reliability of the evidence command and fixes a bug that was preventing evidence to be reported, as seen on the Gaia RS testnet.

BUG FIXES

  • Relayer CLI
    • Improve reliability of evidence command and fix a bug that was preventing evidence to be reported, as seen on the Gaia RS testnet (#3702)

v1.7.2

November 28th, 2023

This patch release of Hermes adds a metric to improve monitoring errors and one to measure the efficiency of the client update skip feature released in patch v1.7.1.

  • broadcast_errors records the number of times a specific error is observed by Hermes when broadcasting transactions.
  • client_updates_skipped records the number of client updates skipped due to the consensus states already existing.

FEATURES

  • Telemetry & Metrics
    • Added metric client_updates_skipped to track the number of client update messages skipped due to the conscensus state existing already. (#3707)
    • Add a new metric broadcast_errors which records the number of times a specific error is observed by Hermes when broadcasting transactions (#3708)

v1.7.1

November 13th, 2023

This patch release of Hermes now allows operators to set the clearing interval at a different value for each chain, using the new per-chain clear_interval setting. The global clear_interval setting is used as a default value if the per-chain setting is not defined.

Additionally, operators can now override the CometBFT compatibility mode to be used for a chain by using the new compat_mode per-chain setting. The main use case for this is to override the automatically detected compatibility mode in case Hermes gets it wrong or encounters a non-standard version number and falls back on the wrong CometBFT version.

On top of that, Hermes will now attempt to save on fees by not building a client update for a given height if the consensus state for that height is already present on chain.

FEATURES

  • Add an optional per-chain setting compat_mode, which can be used to specify which CometBFT compatibility mode is used for interacting with the node over RPC. (#3623)
  • Add a configuration which allows to override the clear_interval for specific chains (#3691)

IMPROVEMENTS

  • Hermes now saves on fees by not including a client update if the consensus state at desired height is already present on chain. (#3521)

v1.7.0

October 20th, 2023

This v1.7 release introduces new features and improvements to Hermes.

One of the key highlights is the addition of new misbehavior detection features.

  • Hermes now includes a new command called evidence, which monitors the blocks emitted by a chain for any presence of misbehavior evidence.
  • If misbehavior is detected, the CLI will report that evidence to all counterparty clients of that chain. On top of that, misbehavior evidence detected on a chain that is a CCV (Cross-Chain Validation) consumer is now sent to its provider chain, alerting it directly of the misbehaving consumer chain.
  • Furthermore, when misbehavior is detected from an on-chain client, such as a light client attack or a double-sign, the evidence is now submitted to all counterparty clients of the misbehaving chain, rather than just the counterparty client of the misbehaving client.

In addition, the REST server of Hermes now has a /clear_packets endpoint which allows triggering packet clearing for a specific chain or all chains if no specific chain is provided.

Another notable improvement is the ability to change tracing directives at runtime. This feature lets users adjust tracing settings dynamically as needed, providing a more customizable and efficient debugging experience.

Overall, the new misbehavior detection features in Hermes contribute to a more robust and secure environment, enabling timely identification and response to potential misbehaving actors.

FEATURES

  • Relayer CLI
    • Add a new evidence command for monitoring the blocks emitted by a chain for the presence of a misbehaviour evidence, and report that evidence to all counteparty clients of that chain. (#3456)
    • Add a /clear_packets?chain=CHAIN_ID endpoint to the built-in REST server to trigger packet clear for the chain specified in the chain query param or for all chains if the query param is omitted. (#3398)
    • Add support for changing tracing directives at runtime. Please see the corresponding page in the Hermes guide for more information. (#3564)

IMPROVEMENTS

  • Relayer Library
    • When Hermes detects a misbehaviour on a chain that is CCV consumer, it will now send the misbehaviour evidence to the provider chain using the new IcsConsumerMisbehaviour message. (#3219)
    • When Hermes detects a misbehaviour from a on-chain client, eg. a light client attack or a double-sign, it will now submit the misbehaviour evidence to all counterparty clients of the misbehaving chain instead of to the counterparty client of the misbehaving client only. (#3223)
    • Improve error message when scanning unsupported client (#3531)
    • Regard the finalize_block_events field of the block_results RPC endpoint, added in CometBFT 0.38 (#3548)
    • Change fallback compatibility version for CometBFT from v0.37 to v0.34 (#3666)
  • Relayer CLI
    • The listen command now works with both push and pull event sources (#3501)

BUG FIXES

v1.6.0

July 19th, 2023

This release of Hermes notably features a new pull-based event source which fetches events from the chain periodically using the /block_results RPC endpoint instead of getting them over WebSocket.

To use the new pull-based event source, set

event_source = { mode = 'pull', interval = '1s' }`

in the per-chain configuration.

Check the event_source setting in the example config.toml file in the Hermes repository for more details.

Additionally, it is now possible to skip the scanning phase during Hermes startup, by disabling clients, connections and channels workers, and setting clear_on_start to false. This significantly improve startup time when relaying on chains with hundreds or thousands of open channels, connections and clients. See the Performance tuning page of the guide for more information.

Note for operators

⚠️ Be aware that this release contains breaking changes to the Hermes configuration. ⚠️ Please consult the UPGRADING.md document for more details.

BREAKING CHANGES

  • The websocket_addr configuration option has been removed in favour of the new event_source setting. Please consult the UPGRADING.md document for more details.
  • Bump MSRV to 1.71 (#3478)

BUG FIXES

  • Relayer CLI
    • Install CA certificates in Docker image for Hermes to be able to connect to TLS endpoints (#3423)
  • Relayer Library
    • Fix a bug where Hermes would discard the client updates corresponding to the supporting headers returned by the light client when assembling messages to relay from the operational data (#3465)

FEATURES

  • Relayer Library

    • Add a pull-based event source which fetches events from the chain periodically using the /block_results RPC endpoint instead of getting them over WebSocket.

      To use the pull-based event source, set event_source = { mode = 'pull', interval = '1s' } in the per-chain configuration.

      Warning Only use this if you think Hermes is not getting all the events it should, eg. when relaying for a CosmWasm-enabled blockchain which emits IBC events in a smart contract where the events lack the message attribute key. See #3190 and #2809 for more background information. (#2850)

  • Integration Test Framework
    • Add integration tests for the Fee Grant module. (#3416)
    • Add a new trait InterchainSecurityChainTest and two functions run_binary_interchain_security_node_test and run_binary_interchain_security_channel_test which can be used to bootstrap a Provider and Consumer chain for integration tests. Add a CI job to run tests with Gaia as a provider chain and Neutron as a Consumer chain. (#3450) (#3387)

IMPROVEMENTS

  • Relayer CLI
    • By disabling clients, connections and channels workers, and setting clear_on_start to false, Hermes will now skip the scanning phase during startup, significantly improve startup time when relaying on chains with hundreds or thousands of open channels, connections and/or clients. See the Performance tuning page of the guide for more information. (#3403)
  • Relayer Library
    • Hermes will now automatically shutdown inactive workers to reduce the consumption of host system resources (#3385)
    • Query the /genesis RPC endpoint to retrieve the value of max_expected_time_per_block and use it for max_block_time. (#3211)
  • Telemetry & Metrics
    • Add two new configurations for the telemetry buckets:
    • latency_submitted used to specify the range and number of buckets for the tx_latency_submitted metric.
    • latency_confirmed used to specify the range and number of buckets for the tx_latency_confirmed metric. (#3366)
  • Integration Test Framework
    • Update ICA tests to use ibc-go's simd instead of interchain-accounts-demo. (#3353)
    • Update simd version used in integration tests from v7.0.0 to v7.1.0 (#3434)

v1.5.1

June 5th, 2023

This is a patch release for Hermes, which includes a single bugfix and enables overflow checks in production builds.

BUG FIXES

  • Fix a panic which can occur when querying connections filtered by counterparty chain using hermes query connections (#3381)

IMPROVEMENTS

  • Overflow checks are now enabled when Hermes is built in release mode, in order to better catch and address potential logic errors leading to overflows (#3390)

v1.5.0

May 24th, 2023

🎉 Hermes v1.5.0 is here, packed with a slew of exciting updates, including breaking changes💥, brand-new features🎁, performance enhancements🚀, and sweeping improvements✨.

The one breaking change is the removal of the unbonding_period setting from the chain configuration. This is now replaced by a fresh ccv_consumer_chain setting for Cross-Chain Validation (CCV) consumer chains.

Also, Hermes has strengthened its misbehavior detection. With the mode.misbehaviour.enabled setting enabled (now the case by default) the relayer was already closely monitoring on-chain client updates, comparing submitted headers with those fetched from its RPC node. In the event of any discrepancy, Hermes would report the misbehaviour to the chain hosting the IBC client. As of this version, Hermes will also report the misbehaviour evidence to the reference chain.

This version rolls out a string of performance enhancements. Event batches are now delivered after a configurable delay, greatly trimming down latency when relaying, particularly on high-traffic channels. This can be adjusted using the batch_delay setting in the per-chain configuration. Plus, packet acknowledgments are only queried when there are packet commitments on the counterparty, resulting in a major speed boost for packet clearing and on-start scanning! 🚀

In addition, the trusted_node setting can now specify whether the full node Hermes connects to is trusted or not. If untrusted, the light client will verify headers included in the ClientUpdate message. However, a word of caution: configuring the full node as trusted may cut down latency but could risk sending invalid client updates to the chain. Use wisely! ⚠️

Our Hermes guide has been re-organized a bit, now featuring a new Performance Tuning page that details the settings for optimizing the performance of the relayer.

For all the debuggers out there, Hermes now equips a new --debug global flag with several selectable values, and two bonus flags, --archive-address and --restart-height that enable a client update following a genesis restart without an IBC upgrade proposal.

When it comes to telemetry, the destination chain is now added to the labels of the confirmed packet metrics.

Take note that some metrics now have the suffix _total. If you're using a running a Grafana dashboard or any other tool relying on the metric names or labels, an update might be needed. The corresponding page in the guide reflects the new metric names and labels for your convenience.

There's also a fresh configuration option to specify the directory used for the keyring store.

From this version onwards, multi-platform (arm64 and amd64) images will be distributed both on Docker Hub and the GitHub Content Repository.

Note for operators

⚠️ Be aware that this release contains a couple breaking ⚠️ changes to the Hermes configuration and telemetry metrics. ⚠️ Please consult the UPGRADING.md document for more details.

BREAKING CHANGES

  • Remove the unbonding_period setting from the chain configuration, which was only used for CCV consumern chains. Instead, use the ccv_consumer_chain setting to identify a CCV consumer chains. (#3125)

  • Due to the update of an internal dependency, some Prometheus metrics now have a _total suffix. Check the corresponding guide page for the list of all metrics, including their new suffixes and labels.

BUG FIXES

  • Support CometBFT when running version checks (#3288)

FEATURES

  • Add ccv_consumer_chain setting to the chain configuration to properly fetch the unbonding period of CCV consumer chains (#3125)

  • Publish multi-platform (arm64/amd64) images to Docker Hub and GHCR (#3303)

  • When enabled for misbehaviour (ie. when mode.misbehaviour.enabled = true), Hermes will now monitor on-chain client updates and verifies the submitted headers comparing with headers it retrieves from its RPC node. If it detects conflicting headers, it will submit a MisbehaviourMsg to the chain hosting the IBC client. In addition, Hermes will now also submit the evidence to the reference chain. (#3224)

  • Add a global flag --debug which can take one or more of the following values, separated by commas:

    • rpc: show RPC debug logs
    • profiling: show profiling information in the console
    • profiling-json: dump the profiling information to a JSON file in the directory specified in PROFILING_DIR env variable if present, or the current directory otherwise. (#2852) #3332)

  • Add two optional flags --archive-address and --restart-height to hermes update client CLI allowing a client update after a genesis restart without an IBC upgrade proposal. (#1152)

PERFORMANCE

  • Emit event batches after a configurable delay. This considerably reduces the latency when relaying and therefore increases performance substantially on high traffic channels. See the batch_delay setting in the per-chain configuration. (#3331)

  • Only query for packet acknowledgments when there are packet commitments on the counterparty, otherwise the query would return all acknowledments on chain, which is excruciatingly slow (#3348)

  • Use /header RPC endpoint instead of /block to reduce pressure on the node and improve performance (#3226)

  • Add a new trusted_node setting to the per-chain configuration to specify whether or not the full node Hermes connects to is trusted. If not trusted (ie. trusted_node = false), Hermes will verify headers included in the ClientUpdate message using the light client.

    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.

    Warning Setting this flag to true may reduce latency but at the expense of potentially sending invalid client updates to the chain, only use when latency is more critical than operating costs. Use at your own risk.

    (#3330)

IMPROVEMENTS

  • Enable misbehaviour detection by default (#3001)
  • Add the destination chain to the labels of the confirmed packet metrics (#3297)
  • Added a configuration to specify the directory used to the keyring store (#1541)
  • Switch away from rouille to axum in telemetry and REST servers (#1658)
  • Add Juno to chains tested in the integration tests (#3235)
  • Add White Whale migaloo chain to ICS29 tests (#3345)

v1.4.1

May 2nd, 2023

This patch release adds support for CometBFT in version checks.

BUG FIXES

  • Support CometBFT when running version checks (#3288)

v1.4.0

March 27th, 2023

Hermes v1.4.0 brings compatibility with chains based on Tendermint/CometBFT 0.37, while retaining compatibility with Tendermint/CometBFT 0.34. This is transparent and does not require any additional configuration.

The relayer now supports ICS consumer chains, which only requires operators to specify the unbonding_period parameter in the chain settings. This is only a temporary requirement, in the future Hermes will seamlessly support consumer chains with minimal changes to the configuration.

This release also deprecates support for chains based on Cosmos SDK 0.43.x and lower, and bumps the compatibility to Cosmos SDK 0.47.x.

The relayer now also allows operators to filter out packets to relay based on whether or not they contain a fee, and the minimal amount of such fee. Please check the relevant documentation in the Hermes guide for more information. Additionally, Hermes now also tracks metrics for ICS29 fees.

This release includes a new query client status CLI to quickly check whether a client is active, expired or frozen.

Crates versions

Crate Version
ibc-relayer-cli v1.4.0
ibc-relayer v0.23.0
ibc-relayer-types v0.23.0
ibc-relayer-rest v0.23.0
ibc-telemetry v0.23.0
ibc-chain-registry v0.23.0
ibc-test-framework v0.23.0

FEATURES

  • Integration Test Framework
    • Add integration tests for incentivized packet filtering (#1966)
  • Relayer Library
    • Add configuration to filter packet relaying with the recv_fee as criteria (#1966)
    • Add automatic version detection and compatibility with both Tendermint/Comet 0.34 and 0.47 (#2971)
  • Relayer CLI
    • Add a query client status command to query whether a client is active, frozen or expired (#3124)
  • Telemetry & Metrics
    • Added metrics ics29_fee_amounts and ics29_period_fees to track fees rewarded to relayers. (#3090)

IMPROVEMENTS

  • General
    • Deprecate support for SDK 0.43. (#2347)
    • Update ibc-proto-rs to v0.28.0. (#3155)
  • Guide
    • Add a section for ICS29 commands in Hermes guide (#3185)
  • Integration Test Framework
    • Use Rust structure instead of Chain's CLI for the packet forward tests (#3037)
  • Relayer CLI
    • Add unbonding_period setting to the chain configuration to enable relaying between ICS consumer chains and other chains (#3112)

BUG FIXES

  • General
    • Rename prometheus.yaml to prometheus.yml to fix docker-compose used when setting up the monitoring platform. (#3106)
  • Relayer Library
    • Ensure the event monitor is shut down cleanly (#3120)
  • Relayer CLI
    • Fix query client consensus to sort the consensus states by height (#3041)

1.3.0

February 17th, 2023

Hermes v1.3.0 adds support for Cross-chain Queries (ICS 031), implements optimistic channel handshake for lower latency, and comes with a major performance improvement when clearing packets on busy channels for chains using a recent version of IBC-Go. This release also brings a few bug fixes related to closing ordered channels and upgrading clients.

See the full release notes below for more details.

General

FEATURES

Guide

IMPROVEMENTS

Hermes - ibc-relayer-cli (v1.3.0)

BUG FIXES

  • Fix error message on client update with expired trusted state (#3054)

Relayer Library - ibc-relayer (v0.22.0)

BREAKING CHANGES

  • Remove query_consensus_states from the ChainEndpoint trait (#2001)
  • The query consensus state command now only list heights and its --heights-only option was removed (#2001)
  • Bump the default trust threshold for new clients from 1/3 to 2/3 (#2876)

FEATURES

  • Enable optimistic channel handshake (#2910)

IMPROVEMENTS

  • Fetch consensus state heights using the more efficient QueryConsensusStateHeights gRPC query instead of fetching all the consensus states themselves using QueryConsensusStates and extracting the heights from the result (#2001)

BUG FIXES

  • Fix proof in timeout on close messages for ordered channels (#3024)
  • Fix upgraded client state latest height in upgrade proposal (#3057)
  • Fix bug where one could sometimes not subscribe to events. This mostly affected the listen command but also external consumers of events via the EventMonitor interface (#3070)

Integration Test Framework - ibc-test-framework (v0.22.0)

BUG FIXES

  • Updated packet forwarding tests to use memo field instead of overloading receiver following packet-forward-middleware v3.0.0 update (#3025)

FEATURES

  • Add integration tests for ICS31 Cross Chain Queries (#2967)

v1.2.0

December 13th, 2022

Hermes v1.2.0 brings a bunch of new features and other improvements, such as support for Ed25519 keys, more robust health check which takes into account the Tendermint min_gas_price setting, and various bug fixes related to the handling of begin- and end-block events in the Tendermint indexer.

Additionally, IBC clients with a trust level between 1/3 and 2/3 inclusive are now allowed.

General

BREAKING CHANGES

  • Update minimum supported Rust version to 1.65.0 (#2817)
  • Update to tendermint-rs 0.28 and ibc-proto 0.24 (#2944)

IMPROVEMENTS

  • Test against Gaia v8 in CI (#2820)
  • Use rolling Ubuntu as base image in Hermes Docker image to reduce fix several vulnerabilities found in previous base image (#2810)

Hermes - ibc-relayer-cli (v1.2.0)

IMPROVEMENTS

  • Collate consecutive heights and sequence numbers shown in logs (#2847)

Relayer Library - ibc-relayer (v0.21.0)

FEATURES

  • Add support for Ed25519 keys (#2851)

BUG FIXES

  • Ensure Hermes uses Rustls instead of OpenSSL for TLS on all platforms (#2799)
  • Fix an issue where Hermes would sometimes fails to retrieve the begin/end block events because of a quirk of the Tendermint event indexer (#2867)
  • Hermes tx CLIs that use the packet_data_query_height option now also clear begin/end block events (#2868)

IMPROVEMENTS

  • The health check process now compares the configured gas_price config setting against the full node's min_gas_price setting, ensuring that the former is at least equal to the latter (#2776)
  • IBC clients with trust thresholds in the range [1/3, 2/3] (inclusive) are now allowed (#2798)
  • Move default implementations of init_event_monitor, id, get_key, and add_key from CosmosSdkChain to ChainEndpoint, and change ChainEndpoint::config() to return a &ChainConfig instead of a ChainConfig (#2806)
  • Remove init_event_monitor from ChainEndpoint in favor of subscribe method (#1456)
  • Added the possibility to specify multiple chains for integration tests (#2003)
  • Clean up secp256k1 signing with other small changes
    • The k256 library is no longer used; instead, secp256k1 is used for both Evmos (aka Ethermint) and Cosmos
    • Move sign_message into KeyEntry and remove the duplicated functions in KeyRing and at the top level
    • Move from_seed_file into KeyEntry
    • Simplify the get_address implementation

Integration Test Framework - ibc-test-framework (v0.21.0)

FEATURES

  • Added integration tests and guide entry for packet forwarding. (#1983)
  • Improved error logs when the height given to upgrade a client is too low. (#2781)
  • Added integration tests for client upgrade. (#2312)

Telemetry & Metrics - ibc-telemetry (v0.21.0)

IMPROVEMENTS

  • Add support for dumping Prometheus metrics to JSON (#2890)

v1.1.0

October 28th, 2022

Note to developers

The ibc and ibc-proto crates have been split into their own repositories under the cosmos organization.

Moreover, Hermes will not be using the original ibc crate anymore, and will from now on use instead the ibc-relayer-types crate, which is a trimmed down version of the ibc crate that contains only the data structures used by Hermes.

This change does not impact end-users of Hermes, but may affect downstream consumers of the ibc-relayer library in some cases.

Please reach out to us if you encounter any issue following from this reorganization of the repository.

General

The gm binary has been split out of the repo and has been moved into its own repository. This change doesn't affect current local instances of the gm binary, though new versions will need to be sourced from the new repository by running git clone informalsystems/gm and running the install script from there.

For more information, see this section of the Hermes guide.

BREAKING CHANGES

  • Removed gm folder and its contents (#2754)
  • Remove the ibc-proto and ibc-proto-compiler crates from the repository (#2667)

BUG FIXES

  • Fix incorrect Github workflow trigger paths (#2667)
  • Fix comment in config.toml to correctly state that the default value of clear_on_start is true (#2750)

Hermes - ibc-relayer-cli (v1.1.0)

FEATURES

  • Add hermes auto config CLI command to automatically generate a config file with data from the chain registry (#2187)
  • Added new optional flag --packet-data-query-height to CLI hermes tx packet-recv in order to specify the height at which the packet data is queried (#2453)
  • New command fee transfer which transfers tokens with fees (#2714)

IMPROVEMENTS

  • Clean up the logs emitted by the relayer and add more structured information to the messages recorded in the logs (#1538)
  • Log the packets cleared by the clear packets command (#2653)
  • Add a new optional flag, --denom to the hermes keys balance command in order to specify for which denomination the balance is queried. Specify the --all flag to get the balance for all denominations (#2726)

Relayer Library - ibc-relayer (v0.20.0)

BREAKING CHANGES

  • Bump tendermint-rs dependencies to v0.25.0 (#2677)

BUG FIXES

  • The channel and connection workers do not act needlessly on NewBlock events anymore (#2484)
  • Fix several bugs which were preventing Hermes to clear packets on ordered channels in some specific conditions, as exhibited on the Interchain Security testnet (#2670)
  • Fix how headers are decoded from events (#2739)

FEATURES

  • Support custom extension options to be able to specify max_priority_price for Ethermint dynamic tx fee (#2566)

IMPROVEMENTS

  • Bump compatibility with IBC-Go v5 and Cosmos SDK v0.46 (#2532)
  • Account for full transaction encoding when batching messages (#2575)
  • Add a health check to warn user if gas_multiplier is smaller than 1.1, and improve client refresh frequency to depend on the trusting_period (#2487)
  • Set max_tx_size default value to 180KB instead of 2MB (#2595)

Chain Registry - ibc-chain-registry (v0.20.0)

  • New crate ibc-chain-registry to fetch data from the chain-registry and query RPC/gRPC endpoints (#2187)

ibc-test-framework (v0.20.0)

FEATURES

  • Added Evmos compatible integration tests (#2442)

Guide

IMPROVEMENTS

  • Integration with mdbook templates (#2605)
  • New script auto_gen_templates.sh to automatically generate templates files and warns users when one of them is updated. It is the responsibility of the users to update the guide when a template file is updated
  • New CI job to check that every template is up-to-date

v1.0.0

August 22nd, 2022

After more than 2 years in the works, this is the first stable release of the Hermes relayer! 🎉

For reaching this milestone, we thank the valuable contributions of over 50 individuals, spread across more than 800 documented & resolved issues. Beside Cosmos-SDK and Tendermint, we are fortunate to maintain some of the most active and intense repository in the Cosmos ecosystem. Most importantly, we thank the relentless work of relayer operators that have already relayed billions worth of value in IBC production networks, and have provided us with invaluable feedback on improving Hermes and raising the overall stability of IBC. Kudos to everyone!

Note for operators

⚠️ If upgrading from Hermes v0.15.0, be aware that this release contains multiple breaking ⚠️ changes to the Hermes command-line interface and configuration. ⚠️ Please consult the UPGRADING document for instructions for more details.

Highlights

  • The performance and reliability of the relayer has been greatly improved
  • Merged commands keys add and keys restore into single command keys add The flag to specify the key name for the CLI command keys add has been changed from -n to -k. Restoring a key now takes a file containing the mnemonic as input instead of directly taking the mnemonic
  • Deprecated gas_adjustment setting in favor of new gas_multiplier setting. Check out the upgrading instructions for more details about the new setting.
  • Updated all CLI commands to take flags instead of positional arguments
  • Renamed query packet unreceived-packets to query packet pending-sends and query packet unreceived-acks to query packet pending-acks
  • Added CLI command keys balance which outputs the balance of an account associated with a key
  • Added CLI command query channel client which outputs the channel's client state
  • Added CLI command query transfer denom-trace which outputs the base denomination and path of a given trace hash
  • Dropped the raw prefix from all the tx raw commands
  • Remove the four duplicate commands:
    • tx raw update-client, which is the same as update client
    • tx raw upgrade-client, which is the same as upgrade client
    • tx raw upgrade-clients, which is the same as upgrade clients
    • tx raw create-client, which is the same as create client
  • A new section was added to guide which describes how the new metrics can be used to observe both the current state of the relayer and the networks it is connected to
  • Added many new metrics to the telemetry. The full list can be found in new the guide section linked above

Change to the versioning scheme

As of v1.0.0-rc.0, the Hermes CLI is now versioned separately from the other crates in the project. As such, the top-level version designates the version of the Hermes CLI, but the other crates in the repository do not necessarily match this version. For example, the ibc and ibc-relayer crates are released under version 0.19.0 for Hermes v1.0.0.

The structure of this changelog has therefore changed as well, changes are now grouped first by crate and then by the type of change, eg. feature, bug fix, etc.

Full release notes

The release notes below only contain the changes introduced since v1.0.0-rc.2. For the full list of changes since v0.15.0, please consult the sections below for v1.0.0-rc.2, v1.0.0-rc.1 and v1.0.0-rc.0.

General

  • Bumped crates to the following versions:
    • ibc-relayer-cli: 1.0.0
    • ibc-proto: 0.20.1
    • ibc: 0.19.0
    • ibc-relayer: 0.19.0
    • ibc-telemetry: 0.19.0
    • ibc-relayer-rest: 0.19.0

Hermes - ibc-relayer-cli (v1.0.0)

  • Release version 1.0.0 of Hermes (ibc-relayer-cli)

IBC Proto - ibc-proto (v0.20.0)

  • Release version 0.20.1 of ibc-proto

IBC Modules - ibc (v0.19.0)

  • Release version 0.19.0 of ibc

BREAKING CHANGES

  • Remove height attribute from IbcEvent and its variants (#2542)

BUG FIXES

  • Fix MsgTimeoutOnClose to verify the channel proof (#2534)

Relayer Library - ibc-relayer (v0.19.0)

  • Release version 0.19.0 of ibc-relayer

FEATURES

  • Introduces discovery phase to initialize Prometheus metrics (#2479)

IMPROVEMENTS

  • Refactor the ChainEndpoint trait to expose the light client functionality directly. Instead of exposing a getter for the LightClient trait, the ChainEndpoint trait now defines the two methods verify_header and check_misbehaviour directly. (#2548)

Telemetry & Metrics - ibc-telemetry (v0.19.0)

  • Release version 0.18.0 of ibc-telemetry

BREAKING CHANGES

  • Multiple fixes related to telemetry, detailed below (#2479)
    • Renamed the following metrics:
      • ibc_client_updates to client_updates_submitted
      • ibc_client_misbehaviours to client_misbehaviours_submitted
      • ibc_receive_packets to receive_packets_confirmed
      • ibc_acknowledgment_packets to acknowledgment_packets_confirmed
      • ibc_timeout_packets to timeout_packets_confirmed
      • cache_hits to queries_cache_hits
      • msg_num to total_messages_submitted
      • send_packet_count to send_packet_events
      • acknowledgement_count to acknowledgement_events
      • cleared_send_packet_count to cleared_send_packet_events
      • cleared_acknowledgment_count to cleared_acknowledgment_events
    • Added the following metric:
      • timeout_events
    • Fixed the following metrics:
      • client_updates_submitted: Now correctly count all ClientUpdate messages
      • total_messages_submitted: Now count only submitted messages
    • Changed telemetry enabled to false in the default config.toml, to match the default value for this parameter
    • Changed misbehaviour to false in the default config.toml, to match the default value for this parameter

REST API - ibc-relayer-rest (v0.19.0)

  • Release version 0.19.0 of ibc-relayer-rest

Guide

General

  • Document all metrics and add a section describing how Hermes metrics can be used to observe both the current state of the Hermes relayer and the networks it is connected to (#2479)

v1.0.0-rc.2

August 8th, 2022

This is the third release candidate for Hermes v1.0.0 🎉

General

  • Bumped crates to the following versions:
    • ibc-relayer-cli: 1.0.0-rc.2
    • ibc-proto: 0.20.0
    • ibc: 0.18.0
    • ibc-relayer: 0.18.0
    • ibc-telemetry: 0.18.0
    • ibc-relayer-rest: 0.18.0
  • Bump tendermint-rs dependencies to 0.23.9

Hermes - ibc-relayer-cli (v1.0.0-rc.2)

  • Release version 1.0.0-rc.2 of Hermes (ibc-relayer-cli)

IBC Proto - ibc-proto (v0.20.0)

  • Release version 0.20.0 of ibc-proto

IBC Modules - ibc (v0.18.0)

  • Release version 0.18.0 of ibc

Relayer Library - ibc-relayer (v0.18.0)

  • Release version 0.18.0 of ibc-relayer

BUG FIXES

  • For the ConnOpenTry and ConnOpenAck steps, wait for the destination app height to be higher than the consensus height, otherwise we fail to complete the handshake when the block times of the two chains involved differ significantly (#2433)
  • Fix code that could result in message batch size growing above the transaction size limit (#2477).

FEATURES

  • Enable connecting to full nodes over IPv6 (#2380)

Telemetry & Metrics - ibc-telemetry (v0.18.0)

  • Release version 0.18.0 of ibc-telemetry

IMPROVEMENTS

  • Improve the metrics
    • Renamed oldest_sequence metric to backlog_oldest_sequence
    • Renamed oldest_timestamp metric to backlog_oldest_timestamp
    • Introduced backlog_size Prometheus metric to complement the other backlog_* data, as a metric reporting how many packets are pending on a channel
    • Ensures the backlog_oldest_sequence and backlog_oldest_timestamp are correctly updated when a timeout occurs or when another relayer clears the channel (#2451)
    • Ensures backlog_timestamp is never updated by a packet with a higher sequence than the oldest pending packet (#2469)

BUG FIXES

  • Fixed a bug with updating of Prometheus metrics in the presence of concurrent relayers (#2467)

REST API - ibc-relayer-rest (v0.18.0)

  • Release version 0.18.0 of ibc-relayer-rest

Guide

IMPROVEMENTS

  • Document how to use HTTP basic authentication in the guide (#2459)
  • Remove tutorial featuring raw commands from the guide (#2466)

v1.0.0-rc.1

July 27th, 2022

This is the second release candidate for Hermes v1.0.0 🎉

Note for operators

⚠️ This release contains multiple breaking changes to the Hermes command-line interface and configuration. ⚠️ Please consult the UPGRADING document for instructions to update to Hermes v1.0.0-rc.1.

General

  • Bump ibc-proto crate to 0.19.1
  • Bump ibc, ibc-relayer, ibc-telemetry, ibc-relayer-rest crates to v0.17.0
  • Bump tendermint-rs dependencies to 0.23.8 (#2455)

Hermes - ibc-relayer-cli (v1.0.0-rc.1)

BREAKING CHANGES

  • Drop the raw prefix from all the tx raw commands (#2315
  • Remove the four duplicate commands:
    • tx raw update-client, which is the same as update client
    • tx raw upgrade-client, which is the same as upgrade client
    • tx raw upgrade-clients, which is the same as upgrade clients
    • tx raw create-client, which is the same as create client
    • (#2315)
  • Rename --a- and --b- prefixes in hermes tx subcommands to --src- and --dst- (#2410)
  • Rename flags of tx upgrade-chain command from --src/--dst to --reference/--host (#2376)
  • The default value of the configuration tx_confirmation in Hermes config.toml has been changed from true to false. (#2408)

BUG FIXES

  • Fixed filtering counterparty chain in Hermes command query channels (#1132)
  • Fixed command tx raw ft-transfer to correctly use the address given by the --receiver flag (#2405)

FEATURES

  • Add an optional --show-counterparty flag to hermes query channels which outputs every channel along with its corresponding port, and the counterparty chain's id, in a pretty way (#2429)
  • New optional flags --counterparty-chain and --verbose for the command query connections (#2310)
  • Added new optional flag --host-chain to filter which clients are upgraded when running upgrade clients command (#2311)

IMPROVEMENTS

  • Hermes command keys add now checks for existing key and overwrites only if the flag --overwrite is passed (#2375)
  • Rename --a- and --b- prefixes in hermes tx subcommands to --src- and --dst- (#2410)
  • Increase default value for gas_multiplier setting to 1.1 (#2435)
  • Output status is now colored in green for success and red for error (#2431)

IBC Proto - ibc-proto (v0.19.1)

IMPROVEMENTS

  • Update Protobuf definitions for IBC-Go to v4.0.0-rc0 and Cosmos SDK to v0.45.6 (#1)

IBC Modules - ibc (v0.17.0)

BREAKING CHANGES

  • Remove provided Ics20Reader::get_channel_escrow_address() implementation and make cosmos_adr028_escrow_address() public. (#37)

BUG FIXES

  • Fix serialization for ICS20 packet data structures (#38)
  • Properly process WriteAcknowledgements on packet callback (#36)
  • Fix write_acknowledgement handler which incorrectly used packet's source_{port, channel} as key for storing acks (#35)

IMPROVEMENTS

  • Propose ADR011 for light client extraction (#2356)

Relayer Library - ibc-relayer (v0.17.0)

BUG FIXES

  • Fix a regression where Hermes would not retry relaying packet on account mismatch error when the sequence number used was smaller than the expected one (#2411)
  • Fix a bug where the relayer would fail to relay any packets when the /acbi_info endpoint of a chain did not include data and version fields (#2444)

Telemetry & Metrics - ibc-telemetry (v0.17.0)

IMPROVEMENTS

  • Updated telemetry metric wallet_balance to f64 and removed downscaling displayed value. Please note that when converting the balance to f64 a loss in precision might be introduced in the displayed value (#2381)
  • Improved naming and description of some telemetry metrics and added histogram buckets for tx_latency metrics (#2408)

v1.0.0-rc.0

July 7th, 2022

This is the first release candidate for Hermes v1.0.0 🎉

Note for operators

⚠️ This release contains multiple breaking changes to the Hermes command-line interface and configuration. ⚠️ Please consult the UPGRADING document for instructions to update to Hermes v1.0.0-rc.0.

Change to the versioning scheme

As of this release, the Hermes CLI will be versioned separately from the other crates in the project. As such, the top-level version designates the version of the Hermes CLI, but the other crates in the repository do not necessarily match this version. For example, the ibc and ibc-relayer crates are released under version 0.16.0.

The structure of this changelog has therefore changed as well, changes are now grouped first by crate and then by the type of change, eg. feature, bug fix, etc.

Hermes - ibc-relayer-cli (v1.0.0-rc.0)

BREAKING CHANGES

  • New ADR which describes the changes to the Hermes commands, specifically the move to flags instead of positional arguments. (#594)
  • Merged commands keys add and keys restore into single command keys add. The flag to specify the key name for the CLI command keys add has been changed from -n to -k. Restoring a key now takes a file containing the mnemonic as input instead of directly taking the mnemonic. (#1075)
  • Deprecate gas_adjustment setting in favor of new gas_multiplier setting (#2174)
  • Updated all CLI commands to take flags instead of positional arguments. (#2239)
  • Rename query packet unreceived-packets to query packet pending-sends and query packet unreceived-acks to query packet pending-acks (#2379)

BUG FIXES

  • CLI command config validate now correctly outputs an error if the configuration file does not exist or is empty. (#2143)
  • Fix the flow for crate connection to ensure success despite concurrent relayers racing to finish the handshake. (#2168)

FEATURES

  • Added CLI command keys balance which outputs the balance of an account associated with a key (#912)
  • Added CLI command query channel client which outputs the channel's client state (#999)
  • Added CLI command query transfer denom-trace which outputs the base denomination and path of a given trace hash (#43)
  • Add unit tests for all Hermes commands with at least one argument (#2358)

IMPROVEMENTS

  • Add support for selecting a specific wallet in the clear packets CLI flow (#2111)
  • Added a required flag --upgrade-height that halts the reference chain at the specified height when performing a client upgrade (#2300)
  • Added --yes flag to the create channel flow to enable skipping the --new-client-connection step (#2317)

IBC Proto - ibc-proto (v0.19.0)

FEATURES

  • Generate gRPC server code under feature 'server' (#2277)

IBC Modules - ibc (v0.16.0)

BREAKING CHANGES

  • Change ChannelId representation to a string, allowing all IDs valid per ICS 024 (#39).

BUG FIXES

  • Fix recv_packet handler incorrectly querying packet_receipt and next_sequence_recv using packet's source_{port, channel}. (#40)
  • Permit channel identifiers with length up to 64 characters, as per the ICS 024 specification. (#39).

IMPROVEMENTS

  • Remove the concept of a zero Height (#1009)
  • Complete ICS20 implementation (#59)
  • Derive serde::{Serialize, Deserialize} for U256. (#41)
  • Remove unnecessary supertraits requirements from ICS20 traits. (#2280)

Relayer Library - ibc-relayer (v0.16.0)

BUG FIXES

  • Fix execute_schedule method dropping operational data due to improper handling of errors. (#2118)
  • Fix duplicate packets being generated on start. (#2093)
  • Use appropriate height when querying for client upgrade state (#2185)
  • Fix the channel handshake issues that occur when concurrent relayers are present (#2254)
  • When Hermes submits N messages to a chain, it will now always gets back N responses, even in the presence of errors. (#2333)

FEATURES

  • Add preliminary support for multiple chain types, which can be specified in the chain configuration. At the moment only the CosmosSdk chain type is supported. (#2240)
  • Add support for fetching & parsing the Tendermint version of a network that Hermes is connected to. (#2301)

IMPROVEMENTS

  • Added handler for SDK error 13 in order to output an understandable error message. (#1400)
  • Do not retry indefinitely on command handling failure in the packet worker (#2155)
  • Consolidate ChainEndpoint::proven_* methods with their corresponding query_* form (#2223)
  • Reduce relaying delay when some account mismatch errors occur during Tx simulation (#2249)

Telemetry & Metrics - ibc-telemetry (v0.16.0)

FEATURES

  • Added new metrics to track the number of relayed SendPacket and WriteAcknowledgement messages, the sequence number and the timestamp of the oldest pending SendPacket (#2175)

v0.15.0

May 23rd, 2022

This release brings a number of bug fixes, some performance improvements, notably when clearing packets, as well as new metrics for better observability of the relayer's operations.

BUG FIXES

  • IBC Modules
    • Fix packet commitment calculation to match ibc-go (#47)
    • Fix incorrect acknowledgement verification (#46)
    • fix connection id mix-up in connection acknowledgement processing (#44)
  • Relayer Library
    • Fix a bug where connection and channel handshakes would fail with non-batching transactions (#1971)
    • Fixed client expiry computation to avoid using local time. (#2180)

FEATURES

  • General
    • Replaced gaia v5 with v7 in E2E tests. (#1986)
  • Relayer Library
    • Add six new metrics: wallet_balance, ws_events, ws_reconnect, tx_latency_submitted, tx_latency_confirmed, msg_num (#2112)

IMPROVEMENTS

  • IBC Modules
    • Remove object capabilities from the modules (#45)
  • Relayer Library
    • Ensure max_msg_num is between 1 and 100 with a default of 30 (#1971)
    • Fixed misleading error message leaking from the misbehavior detection task. (#2031)
    • Added support for incremental processing of packet clearing commands. (#2087)
    • Implement ADR 9: add domain type for request messages that are passed to query functions (#2192)

v0.14.1

May 2nd, 2022

This release improves the reliability of the relayer by fixing an edge case where some queries would fail if they reach a full node after a new block is committed but before the application state updates to reflect the changes in that block.

BUG FIXES

  • Relayer Library
    • Fixed query for application status when application state lags behind blockchain state. (#1970)

v0.14.0

April 27th, 2022

This release notably features a new query packet pending command to list outstanding packet commitments that are either unreceived or pending acknowledgement at both ends of a channel.

The ibc crate now also come with a complete ICS 026 implementation.

Note for operators

There is a new query packet pending command, see above for more information.

The create channel command now requires an existing client and connection, unless the --new-client-connection flag is provided. Please refer to the guide for more information.

BREAKING CHANGES

  • create channel now requires a --new-client-connection flag to create a new client and connection for the channel (#1421)
  • Update MSRV to Rust 1.60 (#2081)

BUG FIXES

  • IBC Modules
    • Make all handlers emit an IbcEvent with current host chain height as height parameter value. (#52)
    • Use the version in the message when handling a MsgConnOpenInit (#51)
  • Relayer Library
    • Fix the connection delay logic to use the timestamp of the host block when the client update header was installed. (#1772)
    • Fixed Hermes retrying mechanism not regenerating operational data for messages (#1792)
    • Adjusted max_block_time default value to 30s (#1998)
    • Fix a bug in the wildcard filter where pattern would match in the middle of a string (#2075)
    • Fixed target height used in misbehavior detection. (#2097)
  • Relayer CLI
    • Skip waiting for confirmation events on tx raw upgrade-chain (#1288)
    • Apply client options specified with the create client command. (#1921)

FEATURES

IMPROVEMENTS

  • General
    • Log missing chain in configuration errors emitted during event processing at debug level (#1936)
    • Update tendermint-rs dependencies to v0.23.6 (#2045)
  • IBC Modules
    • Complete ICS26 implementation (#60)
    • Improve ChannelId validation. (#50)
  • Relayer CLI
    • Change create channel CLI command such that it is more difficult to create clients / connections using it (#1421)
    • Added query packet pending command to list outstanding packet commitments that are either unreceived or pending acknowledgement at both ends of a channel. (#1862)

v0.13.0

March 28th, 2022

Hermes v0.13.0 improves performance by lowering the pressure on the full nodes by adding a caching layer for some queries. It also fixes a bug which could cause an exponential slowdown when relaying between many chains with a low average block time.

This release also add support for wildcards in port and channel identifiers in the packet filter configuration, which enable operators to filter ICA channels based on the port prefix.

Additionally, the IBC Protocol Buffers definitions can now be used from CosmWasm.

Note for operators

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:

  1. The host channels, whose port is icahost
  2. 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`
]

This information can also be found in the Hermes guide.

BUG FIXES

  • Relayer Library
    • Fixed relayer behavior on ordered channels (#1835)
    • Do not spawn packet worker on chan open ack/confirm events (#1991)
    • Fix a bug which would cause the relayer to slow down exponentially when either the average block time was low or when it was relaying on too many chains at once (#2008)

FEATURES

  • IBC Proto
    • Add CosmWasm support to the generated Protobuf code (#4)
      • Add a new client feature to gate the tonic client code, implies the std feature.
      • Add a new json-schema feature to derive schemars::JsonSchema on some proto types, implies the std feature.
      • Add #[serde(default)] to fields that might be omitted by Golang omitempty directive.
      • Change serialization of byte arrays to Base64 for compatibility with Go.
    • Derive Serialize and Deserialize for ibc-proto::ibc::core and ibc_proto::ibc::applications structs, and switch to Google's Protobuf standard types instead of Prost's types. (#3)
  • Relayer Library
    • Added caching layer for hermes start command (#1908)
    • Add support for wildcards in port and channel identifiers in the packet filter configuration, which enable operators to filter ICA channels based on the port prefix (#1927)

IMPROVEMENTS

v0.12.0

February 24th, 2022

This release notably brings compatibility with Cosmos SDK 0.45 and IBC v3.0.0-rc.0, as well as support for non-standard ports in the channel handshake. It also contains a fix for a bug where SendPacket events were duplicated when emitted at EndBlock, and fixes another bug where Hermes would clear packet at startup even when clear_on_start = false. The relayer will now also honor the tracing filter specified in the RUST_LOG environment variable, if any.

Note for operators

As of this release, the relayer will not respond to the SIGHUP signal and will therefore not reload the configuration anymore. This feature has been deemed unnecessary given the recent performance improvements, and it is now recommended to just restart the relayer when the configuration is updated.

Additionally, a new CLI command clear packets has been added for clearing packets in both direction on a given channel.

BUG FIXES

  • IBC Modules
    • Fixed the formatting of NotEnoughTimeElapsed and NotEnoughBlocksElapsed in Tendermint errors (#24)
    • IBC handlers now retrieve the host timestamp from the latest host consensus state (#57)
  • Relayer Library
    • Handle non-standard ports in channel handshake (#1837)
    • Fix duplicate SendPacket events emitted by EndBlock (#1844)
    • Fix support for non-standard ports in channel handshake (#1861, #1837)
    • Fixed bug where Hermes cleared packets at startup, despite clear_on_start = false (#1872)
  • Relayer CLI
    • Disable reloading of configuration upon receiving a SIGHUP signal (#1885)

FEATURES

  • General
    • Upgrade protos and compatibility to IBC v3.0.0-rc.0 and Cosmos SDK v0.45.1 (#5)
  • Relayer CLI
    • Allow overriding the tracing filter with RUST_LOG environment variable (#1895)

IMPROVEMENTS

  • IBC Modules
    • Added more unit tests to verify Tendermint ClientState (#24)
    • Define CapabilityReader and CapabilityKeeper traits (#58)
  • Relayer Library
    • Add two more health checks: tx indexing enabled and historical entries > 0 (#1388)
    • Changed ConnectionEnd::versions method to be non-allocating by having it return a &[Version] instead of Vec<Version> (#55)
  • Relayer CLI
    • Added clear packets command, combining the effects of tx raw packet-recv and tx raw packet-ack (#1834)

v0.11.1

February 4th, 2022

This release mainly adds support for channel events originating from Tendermint ABCI's BeginBlock and EndBlock methods.

BUG FIXES

  • Relayer CLI
    • Do not require a config file to be present for the completions command. (#1822)

IMPROVEMENTS

  • Relayer Library
    • Increased tx confirmation timeout to 300s to prevent aggressive tx resubmission (#1663)
    • Handle channel events originating from Tendermint ABCI's BeginBlock and EndBlock methods (#1793)

v0.11.0

January 27th, 2022

This release notably speeds up the startup time of Hermes, adds options to the create client command to customize the client parameters, makes the deposit denomination configurable in tx raw upgrade-chain via a new --denom flag, and adds a completions CLI command to generate shell auto-completion scripts.

Note for operators

This release includes a breaking change, which requires the configuration file to be edited. The mode.packets.filter configuration option has been removed and is now enabled by default.

Before running Hermes v0.11.0, make sure you remove the mode.packets.filter option from the configuration file.

--- a/config.toml
+++ b/config.toml
@@ -50,18 +50,6 @@ clear_interval = 100
 # Whether or not to clear packets on start. [Default: false]
 clear_on_start = true

-# Enable or disable the filtering mechanism.
-# Valid options are 'true', 'false'.
-# Currently Hermes supports two filters:
-# 1. Packet filtering on a per-chain basis; see the chain-specific
-#   filter specification below in [chains.packet_filter].
-# 2. Filter for all activities based on client state trust threshold; this filter
-#   is parametrized with (numerator = 1, denominator = 3), so that clients with
-#   thresholds different than this will be ignored.
-# If set to 'true', both of the above filters will be enabled.
-# [Default: false]
-filter = false
-
 # Toggle the transaction confirmation mechanism.
 # The tx confirmation mechanism periodically queries the `/tx_search` RPC
 # endpoint to check that previously-submitted transactions

BREAKING CHANGES

  • General
    • Update MSRV to Rust 1.58 (#1765)
    • Update tendermint-rs dependencies to 0.23.5 (#1767)
  • Relayer Library
    • Added a denom member to upgrade_chain::UpgradePlanOptions (#1662)
  • IBC Modules
    • Hide ibc::Timestamp::now() behind clock feature flag (#1612)

BUG FIXES

  • IBC Modules
    • Verify the client consensus proof against the client's consensus state root and not the host's state root #61
    • Initialize consensus metadata on client creation (#1763)

IMPROVEMENTS

  • General
    • Improve startup time of the relayer (#1705)
      • When scanning a chain with filtering enabled and an allow list, skip scanning all the clients and query the allowed channels directly. This results in much fewer queries and a faster start.
      • Add a --full-scan option to hermes start to opt out of the fast start mechanism and do a full scan.
    • Update tendermint-rs to v0.23.4 and harmonize the dependencies to use a single TLS stack. A system installation of OpenSSL is no longer required to build Hermes. (#1641)
    • Remove 1 second sleep in generate_tm_block during testing with mock context. (#1687)
  • IBC Modules
    • Extract all ics24_host::Path variants into their separate types (#1760)
    • Disallow empty CommitmentPrefix and CommitmentProofBytes (#1761)
  • Relayer Library
    • Allow ChainEndpoint implementations to fetch any types of clients and consensus states (#1481)
    • More structural logging in relayer, using tracing spans and key-value pairs. (#1491)
    • Improved documentation w.r.t. keys for Ethermint-based chains (#1785)
  • Relayer CLI
    • Add custom options to the create client command. (#836)
    • Make the deposit denomination configurable in tx raw upgrade-chain via a new --denom flag. (#1662)
    • Update to abscissa_core 0.6.0-rc.0 and clap 3.x (#1777)
    • Add completions CLI command to generate shell auto-completion scripts. (#1789)

v0.10.0

January 13th, 2021

This release notably updates the underlying CLI framework (abscissa) to version 0.6.0-beta.1, which now uses clap for parsing command line arguments. This substantially improves the UX of the CLI, by adding support for --help flags in subcommands and improving help and usage printouts.

The --version option of the create channel subcommand has been renamed to --channel-version, with the old name still supported as an alias. Additionally, the -h short flag on many commands is now -H to avoid clashes with the clap-provided short flag for help.

This release also improves the handling of account sequence mismatch errors, with a recovery mechanism to automatically retry or drop tx upon such errors.

The relayer now also supports dynamic versions in channel open handshake (which is needed by Interchain Accounts), and enables full support for IBC v2.

BREAKING CHANGES

  • General
    • Update MSRV to Rust 1.57 (#1660)
    • Pin tendermint-rs dependencies to =0.23.2 (#1665)
  • IBC Modules
    • Add the frozen_height() method to the ClientState trait (includes breaking changes to the Tendermint ClientState API). (#65)
    • Remove Timestamp API that depended on the chrono crate: (#1665):
      • Timestamp::from_datetime; use From<tendermint::Time>
      • Timestamp::as_datetime, superseded by Timestamp::into_datetime
  • Relayer Library
    • Improve spawning of supervisor worker tasks (#1656)
      • The Supervisor struct is removed.
      • Supervisor is now spawned using the spawn_supervisor function.
  • Relayer CLI
    • Update to abscissa framework version 0.6.0-beta.1, adding support for --help flags in subcommands and improving help and usage printouts. The --version option of the create channel subcommand has been renamed to --channel-version, with the old name still supported as an alias. Additionally, the -h short flag on many commands is now -H to avoid clashes with the clap-provided short flag for help. (#1576, #1743)

BUG FIXES

  • IBC Modules
    • Delete packet commitment instead of acknowledgement in acknowledgePacket #66
    • Set the counterparty_channel_id correctly to fix ICS04 chanOpenAck handler verification (#64)
    • Add missing assertion for non-zero trust-level in Tendermint client initialization. (#63)
    • Fix conversion to Protocol Buffers of ClientState's frozen_height field. (#62)
  • Relayer Library
    • Handle expired client errors in workers (#1543)
    • Perform execute_schedule after handling packet commands in packet worker (#1715)
    • Do not spawn detect misbehavior task if it is disabled in config #1750

FEATURES

  • General
    • Extend CI test suite to include E2E tests using Gaia v6.0.0 #1550
    • Added the extra_wallets parameter to gm to create additional funded wallets.
    • Added the possibility of JSON output to gm by setting the environment variable OUTPUT=json.
    • Added support for fee granters through config file (#1633)
  • IBC Modules
    • Implement proof verification for Tendermint client (ICS07). (#1583)
  • Relayer Library
    • Added a recovery mechanism to automatically retry or drop tx upon account sequence mismatch errors (#1264)
    • Support dynamic versions in channel open handshake & enable full support for ibc-go v2 (#1410)
    • Allow custom proof-specs in chain config (#67)

IMPROVEMENTS

  • General
    • Update CONTRIBUTING.md for latest version of unclog (#1634)
  • IBC Modules
    • More conventional ad-hoc conversion methods on Timestamp (#1665):
    • Timestamp::nanoseconds replaces Timestamp::as_nanoseconds
    • Timestamp::into_datetime substitutes Timestamp::as_datetime
  • Relayer CLI
    • Improve performance of standalone commands by starting the event monitor on-demand (#1063)
    • Increase the default for max_gas from 300_000 to 400_000 (#1636)

v0.9.0, the “Zamfir” release

November 23rd, 2021

This release honors Anca Zamfir, who has lead ibc-rs from its inception and through its first two years of life. The whole team is grateful for her dedication and the nurturing environment she created. To many more achievements, Anca!! 🥂

Notice for operators

This release requires operators to update their Hermes configuration. The mode configuration section now replaces the strategy option.

strategy = 'packets'

If Hermes was configured with strategy = 'packets', then the configuration needs to be changed in the following way:

 [global]
-strategy = 'packets'
 log_level = 'trace'
-clear_packets_interval = 100
-tx_confirmation = true
+
+[mode]
+
+[mode.clients]
+enabled = true
+refresh = true
+misbehaviour = true
+
+[mode.connections]
+enabled = false
+
+[mode.channels]
+enabled = false
+
+[mode.packets]
+enabled = true
+clear_interval = 100
+clear_on_start = true
+filter = false
+tx_confirmation = true
strategy = 'all'

If Hermes was configured to complete connection and channel handshakes as well, ie. with strategy = 'all', then on top of the changes above, mode.connections.enabled and mode.channels.enabled must be set to true.

See the relevant section of the documented config.toml file in the repository for more details.

BUG FIXES

FEATURES

  • General
    • Support for compatibility with gaia Vega upgrade (protos matching ibc-go v1.2.2 and SDK v0.44.3) (#1408)
    • Optimize the WS client to subscribe to IBC events only (instead of all Tx events) (#1534)
  • Relayer Library
    • Allow for more granular control of relaying modes. The mode configuration section replaces the strategy option. (#1518)

IMPROVEMENTS

  • General
    • Upgrade IBC-rs TLA+ MBT models to modern Apalache type annotations (#69)
    • Add architecture.md doc that gives a high-level overview of the structure of the codebase
    • Add some module-level documentation (#1556)
  • IBC Modules
    • Derive PartialEq and Eq on IbcEvent and inner types (#1546)
  • Relayer Library
    • The relayer will now avoid submitting a tx after the simulation failed (in all but one special case) to avoid wasting fees unnecessarily (#1479)
  • Relayer CLI
    • Output errors on a single line if ANSI output is disabled (#1529)
    • Compute fee amount using big integers to prevent overflow when using denominations with high decimal places (#1555)

v0.8.0

October 29th, 2021

This is the final release of version 0.8.0, which now depends on the official releases of the prost and tonic crates. In addition to everything that's included in v0.8.0-pre.1, this release updates the minimum supported Rust version to 1.56, and contains various bug fixes and performance improvements which make the relayer more reliable.

Notice for operators

A new setting was added to the Hermes configuration: max_block_time. This setting specifies 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. For Cosmos-SDK chains a good approximation is timeout_propose + timeout_commit

BREAKING CHANGES

  • Update MSRV to Rust 1.56 and use the 2021 edition (#1519)

BUG FIXES

  • Fix for "new header has a time from the future" chain error which would arise due to clock drift (#1445):
    • Added new config param max_block_time to prevent the problem for appearing in newly-created clients.
    • Added a synchronous waiting in client update logic to allow destination chain to reach a new height before submitting a client update message.
  • Ensure Hermes does not send timeouts for packets that have not expired yet (#1504)

IMPROVEMENTS

  • General
    • Update to official releases of prost 0.9 and tonic 0.6 (#1502)
  • IBC Modules
    • Support for converting ibc::events::IbcEvent into tendermint::abci::Event (#81)
    • Restructure the layout of the ibc crate to match ibc-go's layout (#1436)
    • Implement FromStr<Path> to enable string-encoded paths to be converted into Path identifiers (#1460)
  • Relayer Library
    • Improve performance of misbehaviour checks triggered by an UpdateClient event (#1417)

v0.8.0-pre.1

October 22nd, 2021

This is a pre-release which depends on in-house forks of various Rust libraries. As such, it is advised to avoid depending on the ibc and ibc-relayer crates at version 0.8.0-pre.1.

Hermes v0.8.0-pre.1 is considered stable and it is recommended for all users to update to this version.

This release notably includes a new memo_prefix configuration option for specifying a prefix to be included in the memo of each transaction submitted by Hermes.

Moreover, Hermes is now able to handle SendPacket events originating from Tendermint ABCI's BeginBlock and EndBlock methods (#1231).

BREAKING CHANGES

  • IBC Modules
    • The check_header_and_update_state method of the ClientDef trait (ICS02) has been expanded to facilitate ICS07 (#71)

FEATURES

  • General
    • Add support for the tx.memo field (#1433)
  • IBC Modules
    • Add ICS07 verification functionality by using tendermint-light-client (#71)
  • Relayer Library
    • Add a default_gas setting to be used for submitting a tx when tx simulation fails (#1457)
    • Update compatibility check for IBC-Go dependency (#1464)

IMPROVEMENTS

  • Relayer Library
    • Handle SendPacket events originating from Tendermint ABCI's BeginBlock and EndBlock methods (#1231)
    • Improve error message when create client fails and add a health check for the trusting period being smaller than the unbonding period (#1440)

v0.7.3

October 4th, 2021

This minor release most notably includes a fix for a bug introduced in v0.7.0 where Hermes would always use the max gas when submitting transactions to chains based on Cosmos SDK <= 0.42. It also improves the handling of account sequence numbers

BUG FIXES

  • Relayer Library
    • Fix a bug introduced in Hermes v0.7.0 where tx simulations would fail on chains based on Cosmos SDK 0.42. This would cause Hermes to use the max gas specified in the config when submitted the tx, leading to high fees. (#1345)
    • Only increase cached account sequence number when broadcast_tx_sync fails, therefore ensuring that the cached sequence number stays in sync with the node. (#1402)

IMPROVEMENTS

  • Relayer Library
    • Set default trusting period to be 2/3 of unbonding period for Cosmos chains (#1392)

v0.7.2

September 24th, 2021

This minor release brings substantial performance improvements as well as support for chains using Secp256k1 signatures in consensus votes.

It also bumps the compatibility to Cosmos SDK 0.44.

FEATURES

  • Support for chains which use Secp256k1 signatures in consensus votes (#1155)

  • Modified packet worker to use stubborn strategy (#1290)

  • Skip consensus_heights query in update_client when possible (#1362)

  • Support for disabling tx confirmation mechanism (#1380)

  • gm

    • Binaries in the config can be defined as URLs now.
    • Add the option to set gm-lib path via the $GM_LIB environment variable (#1365)

IMPROVEMENTS

  • Use core and alloc crates for no_std compatibility (#1156)
  • Improve performance of health check, and only perform it on hermes start. Add a hermes health-check command. (#1336)
  • Treat pre-releases of the Cosmos SDK as their standard version in compatibility check (#1337)
  • Bump Cosmos SDK compatibility to v0.44.0 (#1344)
  • Improve reliability of health check (#1382)

v0.7.1

September 14th, 2021

This minor release of Hermes notably features support for Ethermint chains and transfer amounts expressed as a 256-bit unsigned integer. This release also fixes a bug where the chain runtime within the relayer would crash when failing to decode a invalid header included in a ClientUpdate IBC event.

BUG FIXES

  • Fix header decoding error which resulted in killing the chain runtime (#1342)

  • gm

    • Fix gaiad keys add prints to stderr instead of stdout in SDK 0.43 (#1312)
    • Bumped default rpc_timeout in Hermes config to 5 seconds (#1312)

FEATURES

  • Added post-Stargate (v0.5+) Ethermint support (#1267 #1071)

IMPROVEMENTS

  • General

    • Derive Debug, PartialEq and Eq traits for module errors (#1281)
    • Add MBT tests for ICS 07 Client Upgrade (#1311)
    • Add support for uint256 transfer amounts (#1319)

  • ibc

    • Change all *Reader traits to return Result instead of Option (#73)
    • Clean up modules' errors (#72)

v0.7.0

August 24th, 2021

This release of Hermes is the first to be compatible with the development version of Cosmos SDK 0.43. Hermes 0.7.0 also improves the performance and reliability of the relayer, notably by waiting asynchronously for transactions to be confirmed. Additionally, Hermes now includes a REST server which exposes the relayer's internal state over HTTP.

BUG FIXES

  • ibc

    • Set the index of ibc::ics05_port::capabilities::Capability (#74)

  • gm

    • Fix silent exit when requirements are missing

FEATURES

  • General

    • Update CI to test with gaiad v5.0.5 (#1175)

  • ibc-relayer-cli

    • Add keys delete CLI command (#1065)
    • Add --legacy | -l flag to support upgrades for chains built with Cosmos SDK < v0.43.0 (#1287)

  • ibc-relayer

    • Expose the Hermes config and internal state over a REST API (#843)
    • Spawn packet workers only when there are outstanding packets or acknowledgements to relay (#901)
    • Upgrade to Cosmos SDK proto (v0.43.0) & ibc-go proto (v1.0.0) (#948)

IMPROVEMENTS

  • General

    • Update Modelator to 0.2.0 (#1249)

  • ibc-relayer-cli

    • Add optional destination chain and --verbose options for query channels CLI (#1132)

  • ibc-relayer

    • Improve support for Interchain Accounts (ICS 027) (#1191)
    • Improve performance and reliability of the relayer by asynchronously waiting for tx confirmations (#1124, #1265)

  • ibc

    • Implement ics02_client::client_consensus::ConsensusState for AnyConsensusState (#1297)

v0.6.2

August 2nd, 2021

This minor release of Hermes re-enables the upgrade client, upgrade clients, tx raw upgrade-clients, and tx raw upgrade-chain, and otherwise contains a few bug fixes and internal improvements.

Upgrading from version 0.6.1 to 0.6.2 requires no explicit steps.

BUG FIXES

  • Add missing Protobuf impl for ics03_connection::connection::Counterparty (#1247)

FEATURES

  • Augment ClientCreationFailed error with chain id and WS address (#1020)
  • Improve the error message for config file parse errors (#1021)
  • Fix for upgrade CLI regression using new type ics02::TrustThreshold (#1229)

IMPROVEMENTS

  • Add semantic validation of of max_tx_size and max_num_msg config options (#1245)

v0.6.1

July 22nd, 2021

This minor release mainly improves the reliability of the relayer by ensuring that pending packets are cleared on start, and that Hermes can recover from the WebSocket subscriptions being closed under its feet by Tendermint.

Upgrading from version 0.6.0 to 0.6.1 requires no explicit steps.

WARNING: Due to a regression (#1229), the upgrade client, tx raw upgrade-clients, and tx raw upgrade-chain commands have been temporarily disabled in this version. These commands will be re-enabled in the next version.

FEATURES

  • ibc
    • Enable pub access to verification methods of ICS 03 & 04 (#77)
    • Add ics26_routing::handler::decode function (#78)
    • Add a pseudo root to MockConsensusState (#75)

IMPROVEMENTS

BUG FIXES

  • ibc

    • Fix stack overflow in MockHeader implementation (#79)
    • Align as_str and from_str behavior in ClientType (#79)

  • ibc-relayer

    • Ensure pending packets are cleared on start (#1200)
    • Recover from missed RPC events after WebSocket subscription is closed by Tendermint (#1196)

v0.6.0

July 12th, 2021

Many thanks to Fraccaroli Gianmarco (@Fraccaman) for helping us improve the reliability of Hermes (#697).

This release includes two major features to Hermes: (1) support for reloading the chains from the configuration file at runtime, and (2) a filtering mechanism to restrict Hermes activity based on predefined parameters (e.g., packet relaying on certain ports and channels exclusively, and ignoring activity for clients that have non-standard trust threshold).

In addition to these two, we have also added a health checkup mechanism, plus new config validate and query channel ends CLIs.

Upgrading from 0.5.0 to 0.6.0

When upgrading from Hermes v0.5.0 to v0.6.0, the most important point to watch out for is the configuration file. The Hermes config.toml configuration file has went through a few revisions, with the changes described below.

Added inline documentation for all options.

Please have a look around the config.toml directly.

Added a packet filtering mechanism based on channel/port identifiers

This feature will restrict the channels on which Hermes relays packets. There are two new options in the configuration file:

  1. A global filter parameter to enable or disable filtering globally.
  2. A per-chain .filters option that expects a policy (either allow or deny) plus a list of channel and port identifiers. If policy is allow, then packet relaying will be restricted to this list for the corresponding chain. If the policy is deny, then any packets from this list will be ignored.

Added filtering based on client state

The global filter option additionally enables filtering of all activities based on client state trust threshold. If enabled, Hermes will ignore all activity for clients that have a trust threshold different than 1/3.

Added a packet clearing configuration option

This will enable the parametrization of the frequency at which Hermes will clear pending packets. This is a global option, called clear_packets_interval, which applies to all chains in the configuration.

The full list of changes is described below.

FEATURES

  • ibc-relayer

    • The chains configuration can be reloaded by sending the Hermes process a SIGHUP signal (#1117)
    • Added support for filtering based on client state trust threshold (#1165)

  • ibc-relayer-cli

    • Added config validate CLI to Hermes (#600)
    • Added filtering capability to deny or allow for specific channels (#1140, #1141, #69)
    • Added basic channel filter (#1140)
    • Added query channel ends CLI command (#1062)
    • Added a health checkup mechanism for Hermes ([#697, #1057])

IMPROVEMENTS

  • Update to tendermint-rs v0.20.0 (#1125)

  • Add inline documentation to config.toml (#1127)

  • ibc-relayer

    • Hermes will now clear pending packets at a configurable interval (#1124)

BUG FIXES

v0.5.0

June 22nd, 2021

This release brings a few features, and several improvements and bug fixes to the Hermes relayer, notably the capability for Hermes to complete IBC connection handshakes when it detects that one has been initialized, as well as the ability to detect chain impersonation attacks and to dynamically estimate the gas needed to submit a transaction.

Moreover, the overall reliability and availability of the relayer has also been improved substantially by switching over to tx_broadcast_sync for submitting transactions.

FEATURES

  • ibc-relayer-cli

    • Add --hd-path option to keys restore and keys add commands to specify derivation path when importing keys (#1049)

  • ibc-relayer

    • Event-based handshake completion for IBC connections (#821)
    • Enable TLS support for gRPC client (#877)

IMPROVEMENTS

  • ibc-relayer-cli

    • Minor log output improvements: color enabled, reduced redundant information (#1100)

  • ibc-relayer

    • Update the on-chain IBC client with supporting headers when light client verification performs bisection when verifying a header for a client update or a misbehaviour detection (#673)
    • Add mitigation for chain impersonation attacks (#1038)
    • Determine gas fee dynamically per transaction (#930)
    • Submit transactions with broadcast_tx_sync and keep track of account sequences (#986)

BUG FIXES

  • gaiad-manager

    • Removed the testnet command as not all networks support it (#1050)
    • Update for compatibility with Hermes's new --hd-path option

  • ibc-relayer

    • Fix bug where channels were left partially open after channel create (#1064)
    • Prevent account sequence mismatch errors in many cases (#919, #978)
    • Prevent timeouts when submitting transactins (#977)

BREAKING CHANGES

  • ibc-relayer-cli
    • Removed --coin-type option from keys restore command. Use --hd-path instead (#1049)

v0.4.0

June 3rd, 2021

  • This release of Hermes features an internal telemetry service which can export metrics about the relayer to Prometheus.
  • A new relaying strategy is now available, which enables Hermes to complete channel handshakes in an event-based fashion.
  • Hermes now checks if another relayer may have already processed a packet event, and will not attempt to process it itself, which improves performance.
  • The startup time of the relayer has been substantially improved.
  • The start-multi command has been promoted to start, which means that the worker-based relayer is not experimental anymore.
  • A regression where Hermes would not recover after a node went down and up again was fixed.

Special thanks to Colin Axnér (@colin-axner) and Jongwhan Lee (@leejw51crypto) for raising multiple issues that helped us improve the reliability of Hermes.

FEATURES

  • ibc-relayer
    • Add telemetry and Prometheus endpoint (#868, #1032)
    • Add support for event based channel relaying (#822)
    • Graceful handling of packet events in the presence of multiple relayers (#983)

IMPROVEMENTS

  • ibc

    • Started unwrap cleanup (#871)

  • ibc-relayer-cli

    • Include chain-id in query clients command, and sort output by client counter (#992)
    • Improve config loading message (#996)
    • Improve Hermes worker spawn time for start command (#998)
    • Better Hermes help message when command is unrecognized (#1003)

BUG FIXES

  • ibc-relayer

    • Fix client worker initialization error (#972)
    • Fix hermes start panic when all chains are unreachable (#972)
    • Ensure expired or frozen client worker logs message and terminates (#1022)
    • Fix regression where Hermes would not recover after a node went down and up again (#1026)

  • gaiad-manager

    • Import hermes keys properly even if wallet HD derivation path is set (#975)
    • Apply default values to missing configuration parameters (#993)
    • gm hermes config now creates hermes 0.4.0 compatible configuration (#1039)

BREAKING CHANGES

v0.3.2

May 21st, 2021

This is minor release which brings substantial performance improvements to the relayer (relaying 1000 packets now takes 2-5min instead of 1h+), better UX for the ft-transfer command, and automatic deployment of Docker images to Docker Hub.

FEATURES

  • ibc-relayer-cli

    • Add a --key option to the tx raw ft-transfer command to override the account used for sending messages (#963)

  • ibc-relayer

    • Add support for multiple keys to the keyring (#963)

  • [release]

    • Released the official Hermes image on Docker Hub (#894)
    • Automatically deploy Docker Hub image during release (#967)

IMPROVEMENTS

  • ibc-relayer
    • Batch together all events from all transactions included in a block (#957)

BUG FIXES

BREAKING CHANGES

Nothing

v0.3.1

May 14h, 2021

This release improves the UX of a couple commands, fixes a bug related to delay periods, and adds support for packet timeouts based on timestamps, as well as support Protobuf-encoded keys.

FEATURES

  • [scripts]

    • Created the Gaiad Manager gm CLI tool for managing gaiad instances on the local machine (#902)

  • ibc-relayer

    • Add support for packet timeout based on timeout timestamp (#937)
    • Added support for Protobuf-based Keyring (#925)

IMPROVEMENTS

  • ibc-relayer-cli
    • Improve UX when querying non-existing connections and channels (#875, #920)
    • More details in error messages to increase debuggability (#921, #934)
    • Disallow creating a client with same source and destination chains (#932)
    • Make packet worker more resilient to nodes being unreachable for a short amount of time (#943)

BUG FIXES

  • ibc
    • Process raw delay_period field as nanoseconds instead of seconds. (#927)

BREAKING CHANGES

Nothing

v0.3.0

May 7h, 2021

Special thanks to Jongwhan Lee (@leejw51crypto) for his contributions (#80).

This release mostly focuses on improving the UX and the experimental multi-paths relayer (start-multi command), which has been made more resilient against nodes going down, and is now able to clear pending packets and periodically refresh IBC clients. The relayer now also supports ICS 027 (Interchain Accounts).

FEATURES

IMPROVEMENTS

  • ibc

    • Reinstated ics23 dependency (#9)
    • Use proper Timestamp type to track time (#83)

  • ibc-relayer

    • Change the default for client creation to allow governance recovery in case of expiration or misbehaviour (#785)
    • Use a single supervisor in start-multi to subscribe to all configured chains (#862)
    • The start-multi command is now more resilient to a node not being up or going down, and will attempt to reconnect (#871)

BUG FIXES

  • ibc

    • Fix parsing in chain_version when chain identifier has multiple dashes (#80)

  • ibc-relayer

    • Fix pagination in gRPC query for clients (#811)
    • Fix relayer crash when hermes starts in the same time as packets are being sent (#851)
    • Fix missing port information in hermes query channels (#840)
    • Fix crash during initialization of event monitor when node is down (#863)
    • Spawn a single Tokio runtime for the whole supervisor instead of one per chain (#909)

  • ibc-relayer-cli

    • Fix for ft-transfer mismatching arguments (#869)
    • Fix channel destination chain mismatch on unreceived-packets or unreceived-acks (#873)

BREAKING CHANGES

  • ibc-relayer
    • hermes -j query channels command now returns result array with the format [{"channel_id":"channel-0","port_id":"transfer"}, ...] instead of ["channel-0", ...] (#840)

v0.2.0

April 14th, 2021

This release includes initial support for relaying over multiple paths from a single hermes instance. Adds support for relayer restart, where pending packets are cleared. Includes support for ordered channels, packet delay, misbehaviour detection and evidence submission, client upgrade after counterparty chain upgrades.

This release brings improvements to the relayer UX by providing new and updated commands for keys, client, connection and channel management. In addition, it simplifies the configuration of and integration with the light client.

This release also finalizes the initial implementation of all the ICS 004 handlers.

FEATURES

  • Update to tendermint-rs v0.19.0 (#798)

  • ibc

    • Added handler(s) for sending packets (#87), recv. and ack. packets (#85), and timeouts (#101)

  • ibc-relayer

    • Support for relayer restart (#561)
    • Add support for ordered channels (#599)
    • Misbehaviour detection and evidence submission (#632)
    • Use a stateless light client without a runtime (#673)

  • ibc-relayer-cli

    • Added create connection and create channel CLIs (#630, #715)
    • Proposed ADR 006 to describe Hermes v0.2.0 use-cases (#637)
    • Added client-upgrade CLI (#357)
    • Added delay feature for packet relaying (#640)
    • Update gaia to version 4.2.0 for e2e tests on CI (#809)
    • Add start-multi command to relay on all paths defined in the configuration (#748)
    • Add option to specify which events to listen for in listen command (#550)
    • Add option to customise receiver address for ft-transfer command (#806)
    • Add keys restore command to import a signing key from its mnemonic ([#813])

IMPROVEMENTS

  • ibc

    • Follow Rust guidelines naming conventions (#689)
    • Per client structure modules (#740)
    • MBT: use modelator crate (#761)

  • ibc-relayer

    • Consistent identifier handling across ICS 02, 03 and 04 (#91)

  • ibc-relayer-cli

    • Clarified success path for updating a client that is already up-to-date (#734)
    • Added create and update wrappers for client raw commands (#772)
    • Output by default is human-readable, and JSON is optional (#805)

BUG FIXES

  • ibc

    • Fix overflow bug in ICS03 client consensus height verification method (#685)
    • Allow a conn open ack to succeed in the happy case (#699)

  • ibc-relayer

    • Replaced rust-crypto & bitcoin-wallet deprecated dependencies (#352)
    • Fix for hard-coded account number (#752)
    • Fix for chains that don't have cosmos account prefix (#416)
    • Fix for building the trusted_validator_set for the header used in client updates (#770)
    • Don't send MsgAcknowledgment if channel is closed (#675)
    • Fix a bug where the keys addresses had their account prefix overridden by the prefix in the configuration (#751)

  • ibc-relayer-cli

    • Hermes guide: improved installation guideline (#672)
    • Make fee denom and amount configurable (#754)

  • ibc-proto

    • Fix for proto files re-compilation bug (#11)

BREAKING CHANGES

  • ibc

    • MsgConnectionOpenAck.counterparty_connection_id is now a ConnectionId instead of an Option<ConnectionId>(#700)

  • ibc-relayer

    • Remove the light client configuration from the global configuration (#793)

  • ibc-relayer-cli

    • Remove the light add and light rm commands (#793)

v0.1.1

February 17, 2021

This release brings a quick fix for a problem with a dependency of crate ibc-relayer, which causes build & installation issues. Many thanks to @Fraccaman for bringing this problem to our attention! (#672)

Additionally, this release also introduces initial implementation for most of ICS 004 handlers, and several bug fixes and improvements, e.g., refactored some CLI code, refactored the Height type in the IBC Events, and a bug fix involving packet acks in a 3-chain setup. More details below.

FEATURES

  • ibc-relayer
    • Listen to channel close initialization event and perform the close handshake (#560)
    • Updated to tendermint-rs v0.18.1 (#682, #671)

IMPROVEMENTS

BUG FIXES

  • ibc

    • Fix panic in conn open try when no connection id is provided (#626)
    • Disable MBT tests if the "mocks" feature is not enabled (#643)

  • ibc-relayer

    • Quick fix for funty breaking change bug (#665)

  • ibc-relayer-cli

    • Fix wrong acks sent with tx raw packet-ack in a 3-chain setup (#614)

BREAKING CHANGES

  • ibc

    • Implementation of the ChanOpenAck, ChanOpenConfirm, ChanCloseInit, and ChanCloseConfirm handlers (#104)
    • Remove dependency on tendermint-rpc (#90)

  • ibc-relayer-cli

    • Remove the proof option from CLI (#572)

v0.1.0

February 4, 2021

🎉 This release brings the first publication of ibc-relayer and ibc-relayer-cli to crates.io.

Noteworthy changes in this release include:

  • The binary in the ibc-relayer-cli crate was given the name Hermes.
  • We published a comprehensive guide for Hermes at hermes.informal.systems.
  • Major improvements to user experience, in particular at CLI level: JSON output, configurable log output level, dedicated channel handshake command, as well as overall improvements to error display and output.

FEATURES

  • Continuous Integration (CI) end-to-end (e2e) testing with gaia v4 (#32, #582, #602)

  • Add support for streamlining releases (#507)

  • ibc-relayer-cli

    • Implement command to query the channels associated with a connection (#505)
    • JSON output for queries and txs (#500)
    • Added 'required' annotation for CLIs queries & txs; better error display (#555)
    • Implement commands for channel close init and confirm (#94)
    • Implement command to perform the handshake for a new channel (#557)
    • Query all clients command (#552)
    • Query all connections command (#553)
    • Query all channels command (#568)
    • Added a relayer binary guide (#542)
    • Split the dev-env script in setup_chains and init_clients (#577)

  • ibc-relayer

    • Added retry mechanism, restructured relayer (#519)
    • Relay MsgTimeoutOnClose if counterparty channel state is State::Closed

  • ibc

    • Add MsgTimeoutOnClose message type (#563)
    • Implement MsgChannelOpenTry message handler (#93)

IMPROVEMENTS

  • Update to tendermint-rs v0.18.0 (#517, #583)

  • Update to tokio 1.0, prost 0.7 and tonic 0.4 (#527)

  • ibc-relayer-cli

    • Replace ChannelConfig in Channel::new (#511)
    • Add packet-send CLI (#470)
    • UX improvements for relayer txs (#536, #540, #554)
    • Allow running standalone commands concurrently to the main relayer loop (#501)
    • Remove the simd-based integration tests (#593)

  • ibc-relayer

    • Performance improvements (#514, #537)
    • Fix for mismatching bitcoin dep (#525)

  • ibc

    • Clean the validate_basic method (#135)
    • MsgConnectionOpenAck testing improvements (#107)

BUG FIXES:

  • ibc-relayer-cli

    • Help and usage commands show 'hermes' for executable name (#590)

  • ibc

    • Fix for storing ClientType upon 'create-client' (#96)

BREAKING CHANGES:

  • ibc
    • The ibc::handler::Event is removed and handlers now produce ibc::events::IBCEvents (#535)

v0.0.6

December 23, 2020

This release focuses on upgrading the relayer and ibc modules to the latest interfaces from the ecosystem: tendermint-rs v0.17, which brings the protobuf changes from tendermint v0.34.0, plus alignment with the latest cosmos proto versions from v0.40.0-rc5 (sometimes called 'stargate-5').

FEATURES

  • Update to tendermint-rs version 0.17 (#12)

  • Update to cosmos-sdk IBC proto version v0.40.0-rc5 (#12)

  • ibc-relayer

  • ibc-relayer-cli

    • Packet CLIs for recv_packet (#443)
    • Packet CLIs for acknowledging packets (#468)

IMPROVEMENTS

  • ibc-relayer
    • Mock chain (implementing IBC handlers) and integration against CLI (#158)
    • Relayer tests for client update (ping pong) against MockChain (#381)
    • Relayer refactor to improve testing and add semantic dependencies (#447)

v0.0.5

December 2, 2020

This release focuses on implementing relayer and relayer-cli functionality towards a full v0 implementation. We now have the full-stack implementation for supporting client creation & updates, as well as connection- and channel handshakes. We also consolidated our TLA+ specs into an "IBC Core TLA+ specification," and added ICS 020 spec.

Special thanks to external contributors for this release: @CharlyCst (#102, #419).

  • ibc-relayer-cli
    • Add --all option to light rm command to remove all peers for a given chain (#431)

FEATURES

  • Update to tendermint-rs version 0.17-RC3 (#403)
  • changelog Added "unreleased" section in CHANGELOG.MD to help streamline releases (#274)
  • ibc
    • Implement flexible connection id selection (#332)
    • ICS 4 Domain Types for channel handshakes and packets (#105, #134)
    • Introduce LightBlock support for MockContext (#100)
  • ibc-relayer
    • Retrieve account sequence information from a chain using a GRPC client (#18)
    • Implementation of chain runtime for v0 (#330)
    • Integrate relayer spike into ibc-relayer crate (#335)
    • Implement query_header_at_height via plain RPC queries (no light client verification) (#336)
    • Implement the relayer logic for connection handshake messages (#358, #359, #360)
    • Implement the relayer logic for channel handshake messages (#371, #372, #373, #374)
  • ibc-relayer-cli
    • Merge light clients config in relayer config and add commands to add/remove light clients (#348)
    • CLI for client update message (#277)
    • Implement the relayer CLI for connection handshake messages (#358, #359, #360)
    • Implement the relayer CLI for channel handshake messages (#371, #372, #373, #374)
    • Added basic client, connection, and channel lifecycle in relayer v0 (#376, #377, #378)
    • Implement commands to add and list keys for a chain (#363)
    • Allow overriding of peer_id, height and hash in light add command (#428)
  • proto-compiler
    • Refactor and allow specifying a commit at which the Cosmos SDK should be checked out (#17)
    • Add a --tag option to the clone-sdk command to check out a tag instead of a commit (#369)
    • Fix --out command line parameter (instead of --path) (#419)
  • ibc/relayer-spec
    • ICS 020 spec in TLA+ (#386)
    • Prepare IBC Core TLA+ specs (#404)

IMPROVEMENTS

  • ibc-relayer
    • Pin chain runtime against Tokio 0.2 by downgrading for 0.3 to avoid dependency hell (#415, follow up to #402)
  • ibc-relayer-cli
    • Split tasks spawned by CLI commands into their own modules ([#331])
    • V0 command implementation (#346)
  • ibc
    • Split msgs.rs of ICS002 in separate modules (#367)
    • Fixed inconsistent versioning for ICS003 and ICS004 (#97)
    • Fixed get_sign_bytes method for messages (#98)
    • Homogenize ConnectionReader trait so that all functions return owned objects (#102)
    • Align with tendermint-rs in the domain type definition of block::Id (#103)

v0.0.4

October 19, 2020

This release focuses on alignment with the Cosmos ecosystem: adaptations to Tendermint-rs 0.16 and subsequently to 0.17 (0.17.0-rc1), and numerous protobuf updates following latest stargate releases.

Additional highlights:

  • Adding DomainTypes and (de)serialization capability to ICS02 and ICS03 messages and structures.
  • Improvements of the IBC message processor framework (handlers, contexts and mocks).
  • Added initial implementations for the ICS26 (routing module) and ICS18 (basic relayer algorithms module) for use in testing.
  • Also added support for packet handling in the relayer algorithm specifications.

BREAKING CHANGES:

FEATURES:

IMPROVEMENTS:

  • ibc Implemented the DomainType trait for IBC proto structures (#245, #249).
  • ibc & ibc-proto Several improvements to message processors, among which (#115):
    • ICS03 connection handshake protocol initial implementation and tests (#127)
    • Add capability to decode from protobuf Any* type into Tendermint and Mock client states
    • Cleanup Any* client wrappers related code
    • Migrate handlers to newer protobuf definitions (#226)
    • Extend client context mock (#114)
    • Context mock simplifications and cleanup (#111, #295, #296, #297)
  • ibc/ics03 Split msgs.rs in multiple files, implement From for all messages (#112)
  • ibc-proto
    • Move ibc-proto source code into ibc-rs (#23) and fixed code deduplication (#282, #284)
    • Consolidate proto-compiler logic #241
  • ibc/relayer-spec Add support for APALACHE to the Relayer TLA+ spec (#165)
  • ibc-relayer Update to tendermint v.0.16 and integrate with the new light client implementation (#90, #243)

BUG FIXES:

v0.0.3

September 1, 2020

This release focuses on the IBC message processor framework and initial implementations in ICS02 and ICS07. It also introduces an initial specification for the relayer algorithm.

Other highlights:

  • The ibc crate is published as ibc in crates.io
  • ADR-001 and ADR-003 are complete. 🎉

BREAKING CHANGES:

  • ibc Renamed modules crate to ibc crate. Version number for the new crate is not reset. (#198)
  • ibc/ics02 ConnectionIds are now decoded to Vec<ConnectionId> and validated instead of Vec<String> (#123)
  • ibc/ics03 Removed Connection and ConnectionCounterparty traits (#119)
  • ibc/ics04 Removed Channel and ChannelCounterparty traits (#120)

FEATURES:

IMPROVEMENTS:

BUG FIXES:

  • ibc/ics24 Identifiers limit update according to ICS specs (#168)

v0.0.2

August 1, 2020

This release is focused on updating the query system from amino to protobuf, implementing a few queries from the CLI, and establishing an initial testing framework that will support multiple chain types.

It does not target a stable release of Cosmos-SDK chains, but is tracking the latest state of development towards the Cosmos-SDK Stargate release.

BREAKING CHANGES:

  • [ibc|ibc-relayer] Refactor queries, paths, and Chain trait to reduce code and use protobuf instead of Amino. #152, #174, #155
  • [repo] Moved relayer/cli to relayer-cli, relayer/relay to relayer. #183

FEATURES:

IMPROVEMENTS:

  • [ci] Framework (scripts and Github Actions) for integration testing the relayer queries against the Cosmos-SDK's simd binary with prepopulated IBC state in the genesis #140, #184
  • [ibc-relayer|ibc] Implemented better Raw type handling. #156
  • [repo] Add rust-toolchain file. #154

BUG FIXES:

  • ibc Fixed the identifiers limits according to updated ics spec. #189
  • [ibc/relayer] Remove some warnings triggered during compilation due to dependency specification. #132
  • ibc Fix nightly runs. #161
  • [repo] Fix for incomplete licence terms. #153

0.0.1

July 1st, 2020

This is the initial prototype release of an IBC relayer and TLA+ specifications. There are no compatibility guarantees until v0.1.0.

Includes:

  • Configuration file definition and validation
  • Client state, consensus state, connection, channel queries.
    • Note: deserialization is unimplemented as it has dependency on migration to protobuf for ABCI queries
  • Per chain light clients threads are created and headers are periodically retrieved and verified.
  • Per chain IBC event monitor threads are spawned and main event handler that receives them.
    • Note: the event handler just displays the events.
  • IBC Modules partial implementation for datastructures, messages and queries.
  • Some English and TLA+ specifications for Connection & Channel Handshake as well as naive relayer algorithm.