Allow more granular configuration of Hermes modes of operation

.changelog/unreleased/features/ibc-relayer/1518-config-modes.md

@@ -0,0 +1,2 @@
+- Allow for more granular control of relaying modes. The `mode` configuration section replaces the `strategy` option. 
+  ([#1518](https://github.com/informalsystems/ibc-rs/issues/1518))

ci/simple_config.toml

@@ -1,8 +1,25 @@
 [global]
-strategy = 'all'
 log_level = 'trace'
+
+[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
-clear_packets_interval = 100
+tx_confirmation = true
 
 [telemetry]
 enabled = false

config.toml

@@ -1,13 +1,45 @@
 # The global section has parameters that apply globally to the relayer operation.
 [global]
 
-# Specify the strategy to be used by the relayer. Default: 'packets'
-# Two options are currently supported:
-#   - 'all': Relay packets and perform channel and connection handshakes.
-#   - 'packets': Relay packets only.
-strategy = 'packets'
+# Specify the verbosity for the relayer logging output. Default: 'info'
+# Valid options are 'error', 'warn', 'info', 'debug', 'trace'.
+log_level = 'info'
+
 
-# Enable or disable the filtering mechanism. Default: 'false'
+# Specify the mode to be used by the relayer. [Required]
+[mode]
+
+# Specify the client mode.
+[mode.clients]
+# Whether or not to enable the client workers. [Required]
+enabled = false
+# Whether or not to enable periodic refresh of clients. [Default: false]
+refresh = true
+# Whether or not to enable misbehaviour detection for clients. [Default: false]
+misbehaviour = true
+
+# Specify the connections mode.
+[mode.connections]
+# Whether or not to enable the connection workers. [Required]
+enabled = false
+
+# Specify the channels mode.
+[mode.channels]
+# Whether or not to enable the channel workers. [Required]
+enabled = false
+
+# Specify the packets mode.
+[mode.packets]
+# Whether or not to enable the packet workers. [Required]
+enabled = false
+# Parametrize the periodic packet clearing feature.
+# Interval (in number of blocks) at which pending packets
+# should be eagerly cleared. A value of '0' will disable
+# periodic packet clearing. [Default: 100]
+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
@@ -16,24 +48,14 @@ strategy = 'packets'
 #   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
-
-# Specify the verbosity for the relayer logging output. Default: 'info'
-# Valid options are 'error', 'warn', 'info', 'debug', 'trace'.
-log_level = 'info'
-
-# Parametrize the periodic packet clearing feature.
-# Interval (in number of blocks) at which pending packets
-# should be eagerly cleared. A value of '0' will disable
-# periodic packet clearing. Default: 100
-clear_packets_interval = 100
-
 # Toggle the transaction confirmation mechanism.
 # The tx confirmation mechanism periodically queries the `/tx_search` RPC
 # endpoint to check that previously-submitted transactions
 # (to any chain in this config file) have delivered successfully.
 # Experimental feature. Affects telemetry if set to false.
-# Default: true.
+# [Default: true]
 tx_confirmation = true
 
 

docs/architecture/adr-002-ibc-relayer.md

@@ -117,9 +117,28 @@ Below is an example of a configuration file.
 
 ```toml
 [global]
-strategy = "packets"
 log_level = "error"
 
+[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
+
 [[chains]]
   id = "chain_A"
   rpc_addr = "http://localhost:26657"
@@ -172,14 +191,7 @@ pub struct Config {
     pub connections: Option<Vec<Connection>>, 
 }
 
-pub enum Strategy {
-    Packets,
-    HandshakeAndPackets,
-}
-
 pub struct GlobalConfig {
-    pub strategy: Strategy,
-
     /// All valid log levels, as defined in tracing:
     /// https://docs.rs/tracing-core/0.1.17/tracing_core/struct.Level.html
     pub log_level: String,

docs/architecture/adr-006-hermes-v0.2-usecases.md

@@ -252,7 +252,6 @@ of the config file will look as follows:
 
 ```toml
 [global]
-strategy = 'packets'
 log_level = 'error'
 log_json = 'false'
 ```

e2e/e2e/channel.py

@@ -553,10 +553,14 @@ def verify_state(c: Config,
     ibc1: ChainId, ibc0: ChainId,
     ibc1_chan_id: ChannelId, port_id: PortId):
 
-    strategy = toml.load(c.config_file)['global']['strategy']
-    # verify channel state on both chains, should be 'Open' for 'all' strategy, 'Init' otherwise
-
-    if strategy == 'all':
+    mode = toml.load(c.config_file)['mode']
+    clients_enabled = mode['clients']['enabled']
+    conn_enabled = mode['connections']['enabled']
+    chan_enabled = mode['channels']['enabled']
+    packets_enabled = mode['packets']['enabled']
+
+    # verify connection state on both chains, should be 'Open' or 'Init' depending on config 'mode'
+    if clients_enabled and conn_enabled and chan_enabled and packets_enabled:
         sleep(10.0)
         for i in range(20):
             sleep(2.0)
@@ -569,7 +573,7 @@ def verify_state(c: Config,
             assert (ibc0_chan_end.state == 'Open'), (ibc0_chan_end, "state is not Open")
             assert (ibc1_chan_end.state == 'Open'), (ibc1_chan_end, "state is not Open")
 
-    elif strategy == 'packets':
+    else:
         sleep(5.0)
         ibc1_chan_end = query_channel_end(c, ibc1, port_id, ibc1_chan_id)
         assert (ibc1_chan_end.state == 'Init'), (ibc1_chan_end, "state is not Init")

e2e/e2e/connection.py

@@ -263,11 +263,14 @@ def verify_state(c: Config,
     ibc1: ChainId, ibc0: ChainId,
     ibc1_conn_id: ConnectionId):
 
-    strategy = toml.load(c.config_file)['global']['strategy']
-    l.debug(f'Using strategy: {strategy}')
-
-    # verify connection state on both chains, should be 'Open' for 'all' strategy, 'Init' otherwise
-    if strategy == 'all':
+    mode = toml.load(c.config_file)['mode']
+    clients_enabled = mode['clients']['enabled']
+    conn_enabled = mode['connections']['enabled']
+    chan_enabled = mode['channels']['enabled']
+    packets_enabled = mode['packets']['enabled']
+
+    # verify connection state on both chains, should be 'Open' or 'Init' depending on config 'mode'
+    if clients_enabled and conn_enabled and chan_enabled and packets_enabled:
         sleep(10.0)
         for i in range(20):
             sleep(5.0)
@@ -280,7 +283,7 @@ def verify_state(c: Config,
             assert (ibc0_conn_end.state == 'Open'), (ibc0_conn_end, "state is not Open")
             assert (ibc1_conn_end.state == 'Open'), (ibc1_conn_end, "state is not Open")
 
-    elif strategy == 'packets':
+    else:
         sleep(5.0)
         ibc1_conn_end = query_connection_end(c, ibc1, ibc1_conn_id)
         assert (ibc1_conn_end.state == 'Init'), (ibc1_conn_end, "state is not Init")

guide/src/commands/relaying/handshakes.md

@@ -5,11 +5,26 @@ for connections and channels.
 
 ## The `start` Command
 
-To relay packets and handshake messages use `all` as strategy in the `global` section of the configuration file:
+To relay packets and handshake messages configure the `mode` section of the configuration file like so:
 ```toml
 [global]
-strategy = 'all'
 log_level = 'info'
+
+[mode]
+
+[mode.clients]
+enabled = true
+# ...
+
+[mode.connections]
+enabled = true
+
+[mode.channels]
+enabled = true
+
+[mode.packets]
+enabled = true
+# ...
 ```
 
 Then start hermes using the start command:
@@ -28,15 +43,15 @@ the configured chains.
 
 Assuming the events are coming from a `source` chain, the relayer determines the `destination` chain and builds the handshake messages based on these events. These are then sent to the `destination` chain.
 
-In addition to the events described in [Packet Relaying](packets.md#packet-relaying), in the `all` strategy mode the following IBC events are handled:
+In addition to the events described in [Packet Relaying](packets.md#packet-relaying), the following IBC events may be handled:
 
-- Channels:
+- Channels (if `mode.channels.enabled=true`):
   - `chan_open_init`: the relayer builds a `MsgChannelOpenTry` message
   - `chan_open_try`: the relayer builds a `MsgChannelOpenAck` message
   - `chan_open_ack`: the relayer builds a `MsgChannelOpenConfirm` message
   - `chan_open_confirm`: no message is sent out, channel opening is finished
 
-- Connections:
+- Connections (if `mode.connections.enabled=true`):
   - `conn_open_init`: the relayer builds a `MsgConnOpenTry` message
   - `conn_open_try`: the relayer builds a `MsgConnOpenAck` message
   - `conn_open_ack`: the relayer builds a `MsgConnOpenConfirm` message

guide/src/commands/relaying/packets.md

@@ -9,11 +9,26 @@ This section describes the configuration and commands that can be used to start
 
 ## The `start` Command
 
-To relay packets only use `packets` as strategy in the `global` section of the configuration file:
+To relay packets only configure the `mode` section of the configuration file like so:
 ```toml
 [global]
-strategy = 'packets'
 log_level = 'info'
+
+[mode]
+
+[mode.clients]
+enabled = true
+# ...
+
+[mode.connections]
+enabled = false
+
+[mode.channels]
+enabled = false
+
+[mode.packets]
+enabled = true
+# ...
 ```
 
 Then start hermes using the start command:

guide/src/config.md

@@ -49,10 +49,27 @@ Here is a full example of a configuration file with two chains configured:
 
 ```toml
 [global]
-strategy = 'all'
 log_level = 'info'
+
+[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
-clear_packets_interval = 100
+tx_confirmation = true
 
 [rest]
 enabled = true

guide/src/help.md

@@ -89,7 +89,6 @@ Relevant snippet:
 
 ```toml
 [global]
-strategy = 'packets'
 log_level = 'error'
 ```
 

guide/src/tutorials/local-chains/relay-paths/multiple-paths.md

@@ -8,8 +8,27 @@ Follow the steps below to connect three chains together and relay packets betwee
 
     ```toml
     [global]
-    strategy = 'packets'
     log_level = 'info'
+
+    [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
 
     [[chains]]
     id = 'ibc-0'

relayer-cli/src/application.rs

@@ -123,12 +123,21 @@ impl Application for CliApp {
     /// time in app lifecycle when configuration would be loaded if
     /// possible.
     fn after_config(&mut self, config: Self::Cfg) -> Result<(), FrameworkError> {
+        use crate::config::Diagnostic;
+
         // Configure components
         self.state.components.after_config(&config)?;
 
-        validate_config(&config).map_err(|validation_err| {
-            FrameworkErrorKind::ConfigError.context(format!("{}", validation_err))
-        })?;
+        if let Err(diagnostic) = validate_config(&config) {
+            match diagnostic {
+                Diagnostic::Warning(e) => {
+                    tracing::warn!("relayer may be misconfigured: {}", e);
+                }
+                Diagnostic::Error(e) => {
+                    return Err(FrameworkErrorKind::ConfigError.context(e).into());
+                }
+            }
+        };
 
         self.config = Some(config);