IBC Refresh

IBC Refresh automates two routine Hermes relayer jobs — clearing pending packets and updating IBC clients — for a list of channels and clients defined in one YAML file. It logs every run and alerts Discord and/or Slack when a Hermes command fails.

Source on GitHub · Summary on chaintools.tech · MIT licence

Requirements

• Python 3.8 or newer
• Hermes, configured for the chains you list (IBC Refresh calls the hermes binary)

Install

git clone https://github.com/ChainTools-Tech/ibc_refresh.git && cd ibc_refresh
python3 -m venv .venv && . .venv/bin/activate
pip install . requests

requests is used for notifications but is not listed in the package requirements, so install it alongside.

Configuration

log_directory: /home/relayer/.logs/ibc_refresh/
task_log_file: task_execution.log
command_log_file: executed_commands.log
notification_log_file: notifications.log
hermes_path: /home/relayer/.hermes/bin/hermes

notifications:
  - type: discord
    webhook: "https://discord.com/api/webhooks/<ID>/<TOKEN>"
  - type: slack
    webhook: "https://hooks.slack.com/services/<ID>"

tasks:
  - type: clear_packets
    entries:
      - { chain: osmosis-1, port: transfer, channel: channel-73, destination_chain: bitsong-2b }
  - type: update_client
    entries:
      - { host_chain: osmosis-1, client: 07-tendermint-<N>, destination_chain: bitsong-2b }

Key	Meaning
log_directory	Folder for all logs (created if missing)
task_log_file, command_log_file	Log file names inside log_directory
notification_log_file	Optional, default notifications.log
hermes_path	Full path to the Hermes binary
notifications	Optional list of discord / slack webhooks
tasks[].entries (clear_packets)	chain, port, channel; destination_chain is used in log names only
tasks[].entries (update_client)	host_chain, client; destination_chain is used in log names only

Usage

ibc_refresh --config config.yaml --task clear_packets
ibc_refresh --config config.yaml --task update_client
ibc_refresh -c config.yaml -t clear_packets update_client   # both in one run

For each entry it runs:

hermes clear packets --chain <chain> --port <port> --channel <channel>
hermes update client --host-chain <host_chain> --client <client>

Run on a schedule

Example crontab for the relayer user — clear packets every 2 minutes, update clients every 2 hours:

*/2 * * * * /home/relayer/ibc_refresh/.venv/bin/ibc_refresh -c /home/relayer/ibc_refresh/config.yaml -t clear_packets >> /home/relayer/.logs/cron_clearing.log 2>&1
0 */2 * * * /home/relayer/ibc_refresh/.venv/bin/ibc_refresh -c /home/relayer/ibc_refresh/config.yaml -t update_client >> /home/relayer/.logs/cron_update.log 2>&1

Logs and notifications

• task_log_file and command_log_file record what ran; they are rewritten on every run.
• The output of each Hermes command goes to <log_directory>/task_output/<task>/<task>_<chain>_<channel-or-client>_<destination>.log, also rewritten on every run.
• notification_log_file records sent notifications and is appended to.
• A notification is sent only when a Hermes command fails (non-zero exit code), with the command that failed.