ws get_header bids stream draft

Cargo.toml

@@ -79,6 +79,7 @@ subtle = "2.5"
 tempfile = "3.20.0"
 thiserror = "2.0.12"
 tokio = { version = "1.37.0", features = ["full"] }
+tokio-tungstenite = { version = "0.28.0", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
 toml = "0.8.13"
 tonic = { version = "0.12.3", features = ["channel", "prost", "tls"] }
 tonic-build = "0.12.3"
@@ -93,6 +94,7 @@ typenum = "1.17.0"
 unicode-normalization = "0.1.24"
 url = { version = "2.5.0", features = ["serde"] }
 uuid = { version = "1.8.0", features = ["fast-rng", "serde", "v4"] }
+webpki-roots = "1.0"
 
 [patch.crates-io]
 blstrs_plus = { git = "https://github.com/Commit-Boost/blstrs" }

benches/pbs/src/main.rs

@@ -2,7 +2,7 @@ use std::time::{Duration, Instant};
 
 use alloy::primitives::B256;
 use cb_common::{
-    config::RelayConfig,
+    config::{GetHeaderTransport, RelayConfig},
     pbs::{GetHeaderResponse, RelayClient, RelayEntry},
     types::{BlsPublicKey, BlsSecretKey, Chain},
     utils::TestRandomSeed,
@@ -157,6 +157,8 @@ fn get_mock_validator(bench: BenchConfig) -> RelayClient {
         id: None,
         headers: None,
         get_params: None,
+        get_header: GetHeaderTransport::Http,
+        api_key_env: None,
         enable_timing_games: false,
         target_first_request_ms: None,
         frequency_get_header_ms: None,

config.example.toml

@@ -92,6 +92,18 @@ headers = { X-MyCustomHeader = "MyCustomValue" }
 # GET parameters to add to each request URL for this relay
 # OPTIONAL
 get_params = { param1 = "value1", param2 = "value2" }
+# How to fetch headers from this relay.
+#   "http"     -> one request per get_header, at the relay url above
+#   "stream"   -> websocket stream of bid updates, only for relays that support it. Connects to
+#                 ws(s)://<relay url>/eth/v1/builder/header_stream/{slot}/{parent_hash}/{pubkey}.
+#                 The stream stays open for the whole request window and the last bid pushed is the
+#                 one used.
+# OPTIONAL, DEFAULT: "http"
+get_header = "http"
+# Name of the environment variable holding this relay's API key. It is sent as `X-Api-Key` when opening a get_header stream, for relays that require one.
+# Only used when `get_header = "stream"`.
+# OPTIONAL
+# api_key_env = "EXAMPLE_RELAY_API_KEY"
 # Whether to enable timing games, as tuned by `target_first_request_ms` and `frequency_get_header_ms`.
 # NOTE: if neither `target_first_request_ms` nor `frequency_get_header_ms` is set, this flag has no effect.
 #

crates/common/src/config/pbs.rs

@@ -38,6 +38,14 @@ use crate::{
     },
 };
 
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GetHeaderTransport {
+    #[default]
+    Http,
+    Stream,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct RelayConfig {
@@ -50,6 +58,12 @@ pub struct RelayConfig {
     pub headers: Option<HashMap<String, String>>,
     /// Optional GET parameters to add to each request
     pub get_params: Option<HashMap<String, String>>,
+    /// How to fetch headers from this relay
+    #[serde(default)]
+    pub get_header: GetHeaderTransport,
+    /// Name of the env var holding this relay's API key, sent as
+    /// `HEADER_API_KEY` when opening a get_header stream.
+    pub api_key_env: Option<String>,
     /// Whether to enable timing games
     #[serde(default = "default_bool::<false>")]
     pub enable_timing_games: bool,

crates/common/src/pbs/constants.rs

@@ -4,6 +4,8 @@ pub const BUILDER_V1_API_PATH: &str = "/eth/v1/builder";
 pub const BUILDER_V2_API_PATH: &str = "/eth/v2/builder";
 
 pub const GET_HEADER_PATH: &str = "/header/{slot}/{parent_hash}/{pubkey}";
+
+pub const GET_HEADER_STREAM_PATH: &str = "/header_stream";
 pub const GET_STATUS_PATH: &str = "/status";
 pub const REGISTER_VALIDATOR_PATH: &str = "/validators";
 pub const SUBMIT_BLOCK_PATH: &str = "/blinded_blocks";
@@ -17,6 +19,7 @@ pub const HEADER_VERSION_KEY: &str = "X-CommitBoost-Version";
 pub const HEADER_VERSION_VALUE: &str = COMMIT_BOOST_VERSION;
 pub const HEADER_START_TIME_UNIX_MS: &str = "Date-Milliseconds";
 pub const HEADER_TIMEOUT_MS: &str = "X-Timeout-Ms";
+pub const HEADER_API_KEY: &str = "X-Api-Key";
 pub const HEADER_CONSENSUS_VERSION: &str = "Eth-Consensus-Version";
 
 pub const DEFAULT_PBS_JWT_KEY: &str = "DEFAULT_PBS";

crates/common/src/pbs/error.rs

@@ -38,11 +38,21 @@ pub enum PbsError {
 
     #[error("SSZ error: {0}")]
     SszError(#[from] SszValueError),
+
+    #[error("websocket error: {0}")]
+    WebSocket(String),
+
+    #[error("websocket timed out")]
+    WebSocketTimeout,
 }
 
 impl PbsError {
     pub fn is_timeout(&self) -> bool {
-        matches!(self, PbsError::Reqwest(err) if err.is_timeout())
+        match self {
+            PbsError::Reqwest(err) => err.is_timeout(),
+            PbsError::WebSocketTimeout => true,
+            _ => false,
+        }
     }
 
     /// Extract the HTTP status code from relay-originated errors.