reth_rpc_engine_api/
capabilities.rs

1//! Engine API capabilities.
2
3use std::collections::HashSet;
4use tracing::warn;
5
6/// Critical Engine API method prefixes that warrant warnings on capability mismatches.
7///
8/// These are essential for block production and chain synchronization. Missing support
9/// for these methods indicates a significant version mismatch that operators should address.
10const CRITICAL_METHOD_PREFIXES: &[&str] =
11    &["engine_forkchoiceUpdated", "engine_getPayload", "engine_newPayload"];
12
13/// All Engine API capabilities supported by Reth (Ethereum mainnet).
14///
15/// See <https://github.com/ethereum/execution-apis/tree/main/src/engine> for updates.
16pub const CAPABILITIES: &[&str] = &[
17    "engine_forkchoiceUpdatedV1",
18    "engine_forkchoiceUpdatedV2",
19    "engine_forkchoiceUpdatedV3",
20    "engine_forkchoiceUpdatedV4",
21    "engine_getClientVersionV1",
22    "engine_getPayloadV1",
23    "engine_getPayloadV2",
24    "engine_getPayloadV3",
25    "engine_getPayloadV4",
26    "engine_getPayloadV5",
27    "engine_getPayloadV6",
28    "engine_newPayloadV1",
29    "engine_newPayloadV2",
30    "engine_newPayloadV3",
31    "engine_newPayloadV4",
32    "engine_newPayloadV5",
33    "engine_getPayloadBodiesByHashV1",
34    "engine_getPayloadBodiesByHashV2",
35    "engine_getPayloadBodiesByRangeV1",
36    "engine_getPayloadBodiesByRangeV2",
37    "engine_getBlobsV1",
38    "engine_getBlobsV2",
39    "engine_getBlobsV3",
40];
41
42/// Engine API capabilities set.
43#[derive(Debug, Clone)]
44pub struct EngineCapabilities {
45    inner: HashSet<String>,
46}
47
48impl EngineCapabilities {
49    /// Creates from an iterator of capability strings.
50    pub fn new(capabilities: impl IntoIterator<Item = impl Into<String>>) -> Self {
51        Self { inner: capabilities.into_iter().map(Into::into).collect() }
52    }
53
54    /// Returns the capabilities as a list of strings.
55    pub fn list(&self) -> Vec<String> {
56        self.inner.iter().cloned().collect()
57    }
58
59    /// Returns a reference to the inner set.
60    pub const fn as_set(&self) -> &HashSet<String> {
61        &self.inner
62    }
63
64    /// Compares CL capabilities with this EL's capabilities and returns any mismatches.
65    ///
66    /// Called during `engine_exchangeCapabilities` to detect version mismatches
67    /// between the consensus layer and execution layer.
68    pub fn get_capability_mismatches(&self, cl_capabilities: &[String]) -> CapabilityMismatches {
69        let cl_set: HashSet<&str> = cl_capabilities.iter().map(String::as_str).collect();
70
71        // CL has methods EL doesn't support
72        let mut missing_in_el: Vec<_> = cl_capabilities
73            .iter()
74            .filter(|cap| !self.inner.contains(cap.as_str()))
75            .cloned()
76            .collect();
77        missing_in_el.sort_unstable();
78
79        // EL has methods CL doesn't support
80        let mut missing_in_cl: Vec<_> =
81            self.inner.iter().filter(|cap| !cl_set.contains(cap.as_str())).cloned().collect();
82        missing_in_cl.sort_unstable();
83
84        CapabilityMismatches { missing_in_el, missing_in_cl }
85    }
86
87    /// Logs warnings if CL and EL capabilities don't match for critical methods.
88    ///
89    /// Called during `engine_exchangeCapabilities` to warn operators about
90    /// version mismatches between the consensus layer and execution layer.
91    ///
92    /// Only warns about critical methods (`engine_forkchoiceUpdated`, `engine_getPayload`,
93    /// `engine_newPayload`) that are essential for block production and chain synchronization.
94    /// Non-critical methods like `engine_getBlobs` are not warned about since not all
95    /// clients support them.
96    pub fn log_capability_mismatches(&self, cl_capabilities: &[String]) {
97        let mismatches = self.get_capability_mismatches(cl_capabilities);
98
99        let critical_missing_in_el: Vec<_> =
100            mismatches.missing_in_el.iter().filter(|m| is_critical_method(m)).cloned().collect();
101
102        let critical_missing_in_cl: Vec<_> =
103            mismatches.missing_in_cl.iter().filter(|m| is_critical_method(m)).cloned().collect();
104
105        if !critical_missing_in_el.is_empty() {
106            warn!(
107                target: "rpc::engine",
108                missing = ?critical_missing_in_el,
109                "CL supports Engine API methods that Reth doesn't. Consider upgrading Reth."
110            );
111        }
112
113        if !critical_missing_in_cl.is_empty() {
114            warn!(
115                target: "rpc::engine",
116                missing = ?critical_missing_in_cl,
117                "Reth supports Engine API methods that CL doesn't. Consider upgrading your consensus client."
118            );
119        }
120    }
121}
122
123/// Returns `true` if the method is critical for block production and chain synchronization.
124fn is_critical_method(method: &str) -> bool {
125    CRITICAL_METHOD_PREFIXES.iter().any(|prefix| {
126        method.starts_with(prefix) &&
127            method[prefix.len()..]
128                .strip_prefix('V')
129                .is_some_and(|s| s.chars().next().is_some_and(|c| c.is_ascii_digit()))
130    })
131}
132
133impl Default for EngineCapabilities {
134    fn default() -> Self {
135        Self::new(CAPABILITIES.iter().copied())
136    }
137}
138
139/// Result of comparing CL and EL capabilities.
140#[derive(Debug, Default, PartialEq, Eq)]
141pub struct CapabilityMismatches {
142    /// Methods supported by CL but not by EL (Reth).
143    /// Operators should consider upgrading Reth.
144    pub missing_in_el: Vec<String>,
145    /// Methods supported by EL (Reth) but not by CL.
146    /// Operators should consider upgrading their consensus client.
147    pub missing_in_cl: Vec<String>,
148}
149
150impl CapabilityMismatches {
151    /// Returns `true` if there are no mismatches.
152    pub const fn is_empty(&self) -> bool {
153        self.missing_in_el.is_empty() && self.missing_in_cl.is_empty()
154    }
155}
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160
161    #[test]
162    fn test_no_mismatches() {
163        let el = EngineCapabilities::new(["method_a", "method_b"]);
164        let cl = vec!["method_a".to_string(), "method_b".to_string()];
165
166        let result = el.get_capability_mismatches(&cl);
167        assert!(result.is_empty());
168    }
169
170    #[test]
171    fn test_cl_has_extra_methods() {
172        let el = EngineCapabilities::new(["method_a"]);
173        let cl = vec!["method_a".to_string(), "method_b".to_string()];
174
175        let result = el.get_capability_mismatches(&cl);
176        assert_eq!(result.missing_in_el, vec!["method_b"]);
177        assert!(result.missing_in_cl.is_empty());
178    }
179
180    #[test]
181    fn test_el_has_extra_methods() {
182        let el = EngineCapabilities::new(["method_a", "method_b"]);
183        let cl = vec!["method_a".to_string()];
184
185        let result = el.get_capability_mismatches(&cl);
186        assert!(result.missing_in_el.is_empty());
187        assert_eq!(result.missing_in_cl, vec!["method_b"]);
188    }
189
190    #[test]
191    fn test_both_have_extra_methods() {
192        let el = EngineCapabilities::new(["method_a", "method_c"]);
193        let cl = vec!["method_a".to_string(), "method_b".to_string()];
194
195        let result = el.get_capability_mismatches(&cl);
196        assert_eq!(result.missing_in_el, vec!["method_b"]);
197        assert_eq!(result.missing_in_cl, vec!["method_c"]);
198    }
199
200    #[test]
201    fn test_results_are_sorted() {
202        let el = EngineCapabilities::new(["z_method", "a_method"]);
203        let cl = vec!["z_other".to_string(), "a_other".to_string()];
204
205        let result = el.get_capability_mismatches(&cl);
206        assert_eq!(result.missing_in_el, vec!["a_other", "z_other"]);
207        assert_eq!(result.missing_in_cl, vec!["a_method", "z_method"]);
208    }
209
210    #[test]
211    fn test_is_critical_method() {
212        assert!(is_critical_method("engine_forkchoiceUpdatedV1"));
213        assert!(is_critical_method("engine_forkchoiceUpdatedV3"));
214        assert!(is_critical_method("engine_getPayloadV1"));
215        assert!(is_critical_method("engine_getPayloadV4"));
216        assert!(is_critical_method("engine_newPayloadV1"));
217        assert!(is_critical_method("engine_newPayloadV4"));
218
219        assert!(!is_critical_method("engine_getBlobsV1"));
220        assert!(!is_critical_method("engine_getBlobsV3"));
221        assert!(!is_critical_method("engine_getPayloadBodiesByHashV1"));
222        assert!(!is_critical_method("engine_getPayloadBodiesByRangeV1"));
223        assert!(!is_critical_method("engine_getClientVersionV1"));
224    }
225}
reth_rpc_engine_api/capabilities.rs

reth_rpc_engine_api/
capabilities.rs
