IBC Refresh

Overview

IBC Refresh is an automation tool for IBC relayers. It runs Hermes maintenance tasks — clearing pending packets and updating clients — for the chains and channels you define in a configuration file.

Every run is logged to dedicated log files, and results can be sent to Discord or Slack, so relayer operators can schedule routine maintenance with cron and still see what happened.

Key Features

• Automated IBC operations — Runs Hermes clear_packets and update_client tasks based on a configuration file.
• Configurable task execution — Define tasks for multiple chains, ports, channels and clients in config.yaml.
• Comprehensive logging — Task, command and notification logs are written to a dedicated directory for troubleshooting and auditing.
• Notifications — Sends structured alerts about task results to Discord (embeds) and Slack (message blocks).

Installation

Install IBC Refresh from source into a Python environment:

Requirements

• Python 3.8 or newer
• A working Hermes installation (its path is set in the configuration)
• Terminal access for CLI execution

git clone https://github.com/ChainTools-Tech/ibc_refresh.git
cd ibc_refresh
pip install -r requirements.txt
python -m pip install .

Usage

Run one task at a time against your configuration file. Supported tasks are clear_packets and update_client:

# Clear pending IBC packets
ibc_refresh --config config.yaml --task clear_packets

# Update client states between chains
ibc_refresh --config config.yaml --task update_client

Configuration

config.yaml holds the log locations, the Hermes binary path, notification webhooks and the task definitions:

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

notifications:
  - type: discord
    webhook: "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"
  - type: slack
    webhook: "https://hooks.slack.com/services/YOUR_WEBHOOK_URL"

tasks:
  - type: clear_packets
    entries:
      - { chain: osmosis-1, port: transfer, channel: channel-490, destination_chain: acre_9052-1 }
  - type: update_client
    entries:
      - { host_chain: osmosis-1, client: 07-tendermint-2316, destination_chain: acre_9052-1 }

Running on a Schedule

A typical setup clears packets every 2 minutes and updates clients every 2 hours, with output redirected to log files:

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

Logs and Notifications

Related Resources

• Full documentation — Requirements, installation and usage on docs.chaintools.tech
• Hermes relayer documentation — The relayer IBC Refresh drives
• IBC protocol — Background on Inter-Blockchain Communication
• ChainTools IBC paths — The paths we relay and maintain