ePBS Implementation

Cargo.toml

@@ -16,7 +16,6 @@ alloy = { version = "^1.0.35", features = [
     "rpc-types-beacon",
     "serde",
     "signer-local",
-    "ssz",
 ] }
 alloy-primitives = "^1.3.1"
 assert_cmd = "2.1.2"
@@ -42,6 +41,7 @@ const_format = "0.2.34"
 ctr = "0.9.2"
 derive_more = { version = "2.0.1", features = ["deref", "display", "from", "into"] }
 docker-compose-types = "0.16.0"
+arbitrary = "1.4"
 docker-image = "0.2.1"
 ethereum_serde_utils = "0.7.0"
 ethereum_ssz = "0.10"
@@ -54,10 +54,10 @@ indexmap = "2.2.6"
 jsonwebtoken = { version = "9.3.1", default-features = false }
 lazy_static = "1.5.0"
 mediatype = "0.20.0"
-lh_eth2 = { package = "eth2", git = "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/sigp/lighthouse", tag = "v8.1.3", features = ["events"] }
-lh_eth2_keystore = { package = "eth2_keystore", git = "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/sigp/lighthouse", tag = "v8.1.3" }
-lh_bls = { package = "bls", git = "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/sigp/lighthouse", tag = "v8.1.3" }
-lh_types = { package = "types", git = "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/sigp/lighthouse", tag = "v8.1.3" }
+lh_eth2 = { package = "eth2", git = "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/sigp/lighthouse", rev = "31d8cfd40d228c2dd902a67b5142ff6abf00c058", features = ["events"] }
+lh_eth2_keystore = { package = "eth2_keystore", git = "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/sigp/lighthouse", rev = "31d8cfd40d228c2dd902a67b5142ff6abf00c058" }
+lh_bls = { package = "bls", git = "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/sigp/lighthouse", rev = "31d8cfd40d228c2dd902a67b5142ff6abf00c058", features = ["arbitrary"] }
+lh_types = { package = "types", git = "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/sigp/lighthouse", rev = "31d8cfd40d228c2dd902a67b5142ff6abf00c058", features = ["arbitrary"] }
 notify = "8.2.0"
 parking_lot = "0.12.3"
 pbkdf2 = "0.12.2"
@@ -74,7 +74,7 @@ serde = { version = "1.0.202", features = ["derive"] }
 serde_json = "1.0.117"
 serde_yaml = "0.9.33"
 sha2 = "0.10.8"
-ssz_types = "0.11"
+ssz_types = "0.14.1"
 subtle = "2.5"
 tempfile = "3.20.0"
 thiserror = "2.0.12"
@@ -97,4 +97,12 @@ uuid = { version = "1.8.0", features = ["fast-rng", "serde", "v4"] }
 webpki-roots = "1.0"
 
 [patch.crates-io]
-blstrs_plus = { git = "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/Commit-Boost/blstrs" }
+blstrs_plus = { git = "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/Commit-Boost/blstrs", rev = "c4ea6b21193886ee9849867397a62e9c243c1fbb" }
+# Progressive-container ssz stack required by lighthouse-unstable (EIP-7495/7916).
+# A consumer does NOT inherit a dependency's [patch]; mirror lighthouse's here.
+ssz_types = { git = "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/sigp/ssz_types", rev = "9203d56ad2d7bc5f12133d043e085843f81edcd6" }
+milhouse = { git = "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/sigp/milhouse", rev = "c70f128976ac0d60ea65a978dabd117a921c36ee" }
+ethereum_ssz = { git = "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/sigp/ethereum_ssz", rev = "2059c21ba52cd3a7e39a8ad537012b761812a393" }
+ethereum_ssz_derive = { git = "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/sigp/ethereum_ssz", rev = "2059c21ba52cd3a7e39a8ad537012b761812a393" }
+tree_hash = { git = "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/sigp/tree_hash", rev = "03d9fa474586c125f306dd7a00cf46284575a01f" }
+tree_hash_derive = { git = "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/sigp/tree_hash", rev = "03d9fa474586c125f306dd7a00cf46284575a01f" }

benches/pbs/src/main.rs

@@ -161,7 +161,10 @@ fn get_mock_validator(bench: BenchConfig) -> RelayClient {
         enable_timing_games: false,
         target_first_request_ms: None,
         frequency_get_header_ms: None,
+        bid_poll_timeout_ms: None,
         validator_registration_batch_size: None,
+        max_execution_payment_gwei: None,
+        expected_auth_data: None,
     };
 
     RelayClient::new(config).unwrap()

config.example.toml

@@ -28,9 +28,17 @@ relay_check = true
 # OPTIONAL, DEFAULT: true
 wait_all_registrations = true
 # Timeout in milliseconds for the `get_header` call to relays. Note that the CL has also a timeout (e.g. 1 second) so
-# this should be lower than that, leaving some margin for overhead
+# this should be lower than that, leaving some margin for overhead.
+# LEGACY get_header path only: the ePBS bid path derives its timeout from the beacon node's own
+# X-Timeout-Ms header instead (see proposer_deadline_buffer_ms below).
 # OPTIONAL, DEFAULT: 950
 timeout_get_header_ms = 950
+# ePBS bid path only. The beacon node sends CB its own deadline (X-Timeout-Ms) on every bid request,
+# so CB no longer needs a static timeout: it asks the builder for `deadline - proposer_deadline_buffer_ms`,
+# reserving this many ms for the winning bid's return trip to the beacon node and the node's own
+# bid-selection/assembly. Configure the margin directly instead of a deadline-minus-margin absolute.
+# OPTIONAL, DEFAULT: 50
+proposer_deadline_buffer_ms = 50
 # Timeout in milliseconds for the `submit_blinded_block` call to relays.
 # OPTIONAL, DEFAULT: 4000
 timeout_get_payload_ms = 4000
@@ -44,6 +52,34 @@ skip_sigverify = false
 # Can be specified as a float or a string for extra precision (e.g. "0.01")
 # OPTIONAL, DEFAULT: 0.0
 min_bid_eth = 0.0
+# Projection-only: consumed by KM tooling, not read by the PBS runtime.
+# The ePBS KEY-LEVEL minimum total payment in ETH: it governs p2p bids and builder entries that
+# omit their own min_bid (projected entries always carry explicit per-entry values sourced from
+# the mux/global min_bid). Float or string
+# OPTIONAL, DEFAULT: unset (key level = mux/global min_bid)
+# min_bid_p2p_eth = "0.2"
+# Projection-only: consumed by KM tooling, not read by the PBS runtime.
+# The ePBS KEY-LEVEL builder_boost_factor: it governs p2p bids and builder entries that omit
+# their own (entry values stay mux-sourced)
+# OPTIONAL, DEFAULT: unset
+# builder_boost_factor_p2p = 100
+# Execution-payment cap in Gwei used when ranking ePBS bids: a bid ranks at
+# `value + min(execution_payment, cap)`, matching how the beacon node values it (the BN clamps the
+# trusted payment at the cap instead of rejecting the bid). This does not accept or reject bids.
+# Can be overridden per relay with `max_execution_payment_gwei` on the relay entry
+# OPTIONAL, DEFAULT: unset (unclamped)
+# max_execution_payment_gwei = 1000000000
+# Whether to verify the BLS signature of the `SignedBuilderRequestAuth` on an ePBS request against the
+# proposer pubkey in the request path, rejecting a bad signature with 401. CB forwards by default
+# because the downstream builder must re-verify anyway; operators terminating trust at CB set it true
+# OPTIONAL, DEFAULT: false
+verify_builder_request_auth = false
+# Strict decoding of the reveal at POST /eth/v1/builder/beacon_blocks. Default (false): CB is a blind
+# pipe, forwarding the reveal bytes to the builder without parsing them, so the reveal MUST be SSZ in
+# blind mode (the builder validates and rejects a bad block per builder-specs). When true: CB decodes
+# the gloas SignedBeaconBlock itself and rejects a non-gloas or otherwise undecodable body with a 400
+# OPTIONAL, DEFAULT: false
+# strict_block_decode = false
 # How late in milliseconds in the slot is "late". This impacts the `get_header` requests, by shortening timeouts for `get_header` calls to
 # relays and make sure a header is returned within this deadline. If the request from the CL comes later in the slot, then fetching headers is skipped
 # to force local building and miniminzing the risk of missed slots. See also the timing games section below
@@ -78,6 +114,18 @@ validator_registration_batch_size = ""
 # enabled, this value will not be used.
 # OPTIONAL, DEFAULT: 384
 mux_registry_refresh_interval_seconds = 384
+# Commit-Boost's externally-reachable URLs, i.e. the ones a validator client's builder config points
+# at. Gates the ePBS pipe: when a request's auth data names a builder URL no configured relay serves,
+# CB dials that URL directly through a transient client (trust is the validator client's job via its
+# keymanager builder_pubkeys). Since an unconfigured key's auth data defaults to CB's own URL, the
+# pipe first checks the decoded URL against this list and rejects a match instead of dialing itself.
+# The guard fails closed: while this list is empty, unmatched auth data is always rejected and the
+# pipe never dials, so set it to enable piping to builders outside the [[relays]] below.
+# List EVERY scheme/host/IP form CB is reachable by: the self-URL guard matches on scheme+host+port
+# exactly, so an equivalent form you omit (e.g. an IP instead of a hostname, or http vs https) is not
+# recognized as CB's own and the pipe could self-dial.
+# OPTIONAL, DEFAULT: []
+# advertised_urls = ["http://cb.example.com:18550"]
 
 # The PBS module needs one or more [[relays]] as defined below.
 [[relays]]
@@ -130,6 +178,21 @@ target_first_request_ms = 200
 # Frequency in ms to send get_header requests
 # OPTIONAL
 frequency_get_header_ms = 300
+# How long each ePBS bid poll may take, in ms. Every poll shares the proposer's deadline, so bounding
+# the early ones lands a floor of progressively better bids instead of leaving everything to the last
+# instant; the final poll always holds for the remaining budget. Set this above your round trip to
+# the builder, or every early poll times out
+# OPTIONAL, DEFAULT: 500
+# bid_poll_timeout_ms = 500
+# Per-relay override of the ePBS bid-ranking execution-payment cap in Gwei (see the PBS-level
+# `max_execution_payment_gwei`)
+# OPTIONAL, DEFAULT: the PBS-level `max_execution_payment_gwei` (unset = unclamped)
+# max_execution_payment_gwei = 1000000000
+# The ePBS auth data this relay serves: a bid request routes here only when its `auth.message.data`
+# equals this value. When unset, the relay is matched only by auth data carrying its URL; auth data
+# matching no configured relay is rejected with 400
+# OPTIONAL, DEFAULT: unset
+# expected_auth_data = "0x68747470733a2f2f6275696c6465722e6578616d706c652e636f6d"
 
 # Configuration for the PBS multiplexers, which enable different configs to be used for get header requests, depending on validator pubkey
 # Note that:
@@ -145,6 +208,20 @@ validator_pubkeys = [
     "0x80c7f782b2467c5898c5516a8b6595d75623960b4afc4f71ee07d40985d20e117ba35e7cd352a3e75fb85a8668a3b745",
     "0xa119589bb33ef52acbb8116832bec2b58fca590fe5c85eac5d3230b44d5bc09fe73ccd21f88eab31d6de16194d17782e",
 ]
+# Projection-only: consumed by KM tooling (builder_config projection for this mux's keys), not read
+# by the PBS runtime
+# OPTIONAL, DEFAULT: unset
+# builder_boost_factor = 100
+# Projection-only: the per-key-group minimum total payment for this mux's keys, in ETH (same format
+# as the PBS-level `min_bid_eth`). Consumed by KM tooling, not read by the PBS runtime
+# OPTIONAL, DEFAULT: unset
+# min_bid_eth = 0.0
+# Projection-only: the KEY-LEVEL p2p overrides for this mux's keys. Consumed by KM tooling, not read
+# by the PBS runtime. When set they take precedence over the PBS-level `builder_boost_factor_p2p` /
+# `min_bid_p2p_eth`; unset inherits the PBS-level value
+# OPTIONAL, DEFAULT: unset (inherit the PBS-level p2p value)
+# builder_boost_factor_p2p = 100
+# min_bid_p2p_eth = "0.2"
 # Loader for validator pubkeys. Three types of loaders are supported:
 #   - File: path to a file containing a list of validator pubkeys in JSON format
 #   - URL: URL to an HTTP endpoint returning a list of validator pubkeys in JSON format

crates/common/Cargo.toml

@@ -11,6 +11,7 @@ testing-flags = []
 [dependencies]
 aes.workspace = true
 alloy.workspace = true
+arbitrary.workspace = true
 async-trait.workspace = true
 axum.workspace = true
 base64.workspace = true
@@ -53,10 +54,10 @@ tracing-appender.workspace = true
 tracing-subscriber.workspace = true
 tree_hash.workspace = true
 tree_hash_derive.workspace = true
+typenum.workspace = true
 unicode-normalization.workspace = true
 url.workspace = true
 uuid.workspace = true
-reqwest-eventsource.workspace = true
 
 [dev-dependencies]
-  tempfile.workspace = true
+  tempfile.workspace = true

crates/common/src/config/log.rs

@@ -16,7 +16,9 @@ pub struct LogsSettings {
 
 impl LogsSettings {
     pub fn from_env_config() -> Result<Self> {
-        let (mut config, _) = CommitBoostConfig::from_env_path()?;
+        // Silent load: the service's primary config load already warns about
+        // unknown mux fields; warning here too would log each key twice
+        let (mut config, _) = CommitBoostConfig::from_env_path_silent()?;
 
         // Override log dir path if env var is set
         if let Some(log_dir) = load_optional_env_var(LOGS_DIR_ENV) {

crates/common/src/config/mod.rs

@@ -52,17 +52,33 @@ impl CommitBoostConfig {
             )
         }
 
+        for relay in self.relays.iter() {
+            relay.validate()?;
+        }
+
         Ok(())
     }
 
     pub fn from_file(path: &PathBuf) -> Result<Self> {
         let (config, _): (Self, _) = load_from_file(path)?;
+        warn_unknown_mux_fields(path);
+        warn_unknown_pbs_fields(path);
         Ok(config)
     }
 
     // When loading the config from the environment, it's important that every path
     // is replaced with the correct value if the config is loaded inside a container
     pub fn from_env_path() -> Result<(Self, PathBuf)> {
+        let (config, config_path) = Self::from_env_path_silent()?;
+        warn_unknown_mux_fields(&config_path);
+        warn_unknown_pbs_fields(&config_path);
+        Ok((config, config_path))
+    }
+
+    /// [`Self::from_env_path`] without the unknown-mux-field warnings. For
+    /// secondary loads (e.g. log settings) in processes whose primary config
+    /// load already warns, so each unknown key is logged once per process.
+    pub(crate) fn from_env_path_silent() -> Result<(Self, PathBuf)> {
         let (helper_config, config_path): (HelperConfig, PathBuf) = load_file_from_env(CONFIG_ENV)?;
 
         let chain = match helper_config.chain {