Document clock drift parameters in guide (#3420)

* Add clock-drift.md file to guide * Add section on mis-configuring clock drift * Update guide/src/advanced/troubleshooting/clock-drift.md Co-authored-by: Anca Zamfir <ancazamfir@users.noreply.github.com> Signed-off-by: Sean Chen <seanchen11235@gmail.com> * Update guide/src/advanced/troubleshooting/clock-drift.md Co-authored-by: Anca Zamfir <ancazamfir@users.noreply.github.com> Signed-off-by: Sean Chen <seanchen11235@gmail.com> * Remove redundant section * Update guide/src/advanced/troubleshooting/clock-drift.md Co-authored-by: Anca Zamfir <ancazamfir@users.noreply.github.com> Signed-off-by: Sean Chen <seanchen11235@gmail.com> * Update guide/src/advanced/troubleshooting/clock-drift.md Co-authored-by: Anca Zamfir <ancazamfir@users.noreply.github.com> Signed-off-by: Sean Chen <seanchen11235@gmail.com> * Explain what `C` constant represents * Add reference to forward lunatic attack --------- Signed-off-by: Sean Chen <seanchen11235@gmail.com> Co-authored-by: Anca Zamfir <ancazamfir@users.noreply.github.com>
informalsystems · Jul 14, 2023 · 2e6b2d4 · 2e6b2d4
1 parent cfd005b
commit 2e6b2d4
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 0 deletions.
diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -49,6 +49,7 @@
         - [Inspecting the relayer's state](./advanced/troubleshooting/inspect.md)
         - [Cross Stack Misconfiguration](./advanced/troubleshooting/cross-comp-config.md)
         - [Genesis restart without IBC upgrade proposal](./advanced/troubleshooting/genesis-restart.md)
+        - [Handling Clock Drift](./advanced/troubleshooting/clock-drift.md)
 
 - [Commands Reference](./documentation/commands/index.md)
   - [Global options and JSON output](./documentation/commands/global.md)

diff --git a/guide/src/advanced/troubleshooting/clock-drift.md b/guide/src/advanced/troubleshooting/clock-drift.md
@@ -0,0 +1,34 @@
+# Handling Clock Drift
+
+IBC light client security model requires that the timestamp of a header included in client updates for some `client` is within `[now - client.trusting_period, now + client.max_clock_drift)`.
+
+The `trusting_period` is a parameter that is configurable under the `[[chains]]` section and its default value is two thirds of the chain `unbonding_period`.
+The rest of this section describes the configuration parameters that determine the `max_clock_drift`.
+
+IBC light client security model requires that the clocks of the reference and host chains are roughly synchronized. Hermes uses the `clock_drift` and `max_block_time` configuration parameters to determine how much clock drift is tolerable between the reference and host chains.
+ - `clock_drift` is a correction parameter that specifies how far in the future or past a chain's clock may be from the current time..
+ - `max_block_time` is the maximum amount of time that can occur before a new block is created on the chain. 
+
+> **Note:** For Cosmos SDK chains, a good approximation for `max_block_time` is `C * (timeout_propose + timeout_commit)`,
+where `C` is a constant to allow for variation in block times, mainly due to tx execution time which is outside of 
+consensus params. To allow for some variance in block times while still detecting [forward lunatic attacks][forward-lunatic], 
+it is recommended to set `C` to be in the `3..5` range. Hermes uses the default value of `30s` which is a good approximation 
+for most Cosmos SDK chains that have 6-10sec block times.
+
+The `clock_drift` parameter values on both the reference and host chains, and `max_block_time` of the host chain are summed to get the `max_clock_drift` when creating a client on the host chain.
+This can be summarized more succinctly in the following equation: 
+```
+client.max_clock_drift = reference.clock_drift + host.max_block_time + host.clock_drift
+```
+
+Thus, when configuring these values in Hermes' `config.toml`, keep in mind that this is how these 
+parameters will be used. If the total clock drift is too small, then we run the risk of client
+updates being rejected because a new block won't have been created yet. It's better to err on the
+side of total clock drift being larger than smaller, however, if this value ends up being _too_
+large, then this becomes a security vulnerability.
+
+For a more concrete example of what could happen when clock drift is mis-configured, take a look
+at the [Mishandling Clock Drift][mishandling-clock-drift] troubleshooting section.
+
+[forward-lunatic]: https://github.com/cometbft/cometbft/blob/main/docs/architecture/tendermint-core/adr-047-handling-evidence-from-light-client.md#appendix-b
+[mishandling-clock-drift]: ./cross-comp-config.md#mishandling-clock-drift