Add support for validation bypassing (#422)

Author: jclapis

Cargo.lock

@@ -49,9 +49,16 @@ min_bid_eth = 0.0
 # to force local building and miniminzing the risk of missed slots. See also the timing games section below
 # OPTIONAL, DEFAULT: 2000
 late_in_slot_time_ms = 2000
-# Whether to enable extra validation of get_header responses, if this is enabled `rpc_url` must also be set
-# OPTIONAL, DEFAULT: false
-extra_validation_enabled = false
+# The level of validation to perform on get_header responses. Less is faster but not as safe. Supported values:
+#   - "none": no validation, just accept the bid provided by the relay as-is and pass it back without decoding or checking it
+#   - "standard": perform standard validation of the header provided by the relay, which checks the bid's signature and several hashes to make sure it's legal (default)
+#   - "extra": perform extra validation on top of standard validation, which includes checking the bid against the execution layer via the `rpc_url` (requires `rpc_url` to be set)
+# OPTIONAL, DEFAULT: standard
+header_validation_mode = "standard"
+# The level of validation to perform on submit_block responses. Less is faster but not as safe. Supported values:
+#   - "none": no validation, just accept the full unblinded block provided by the relay as-is and pass it back without decoding or checking it
+#   - "standard": perform standard validation of the unblinded block provided by the relay, which verifies things like the included KZG commitments and the block hash (default)
+block_validation_mode = "standard"
 # Execution Layer RPC url to use for extra validation
 # OPTIONAL
 # rpc_url = "https://ethereum-holesky-rpc.publicnode.com"

config.example.toml

@@ -36,6 +36,34 @@ use crate::{
     },
 };
 
+/// Header validation modes for get_header responses
+#[derive(Debug, Copy, Clone, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum HeaderValidationMode {
+    // Bypass all validation and minimize decoding, which is faster but requires complete trust in
+    // the relays
+    None,
+
+    // Validate the header itself, ensuring that it's for a correct block on the correct chain and
+    // fork. This is the default mode.
+    Standard,
+
+    // Standard header validation, plus validation that the parent block is correct as well
+    Extra,
+}
+
+/// Block validation modes for submit_block responses
+#[derive(Debug, Copy, Clone, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum BlockValidationMode {
+    // Bypass all validation, which is faster but requires complete trust in the relays
+    None,
+
+    // Validate the block matches the header previously received from get_header and that it's for
+    // the correct chain and fork. This is the default mode.
+    Standard,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct RelayConfig {
@@ -120,8 +148,11 @@ pub struct PbsConfig {
     #[serde(default = "default_u64::<LATE_IN_SLOT_TIME_MS>")]
     pub late_in_slot_time_ms: u64,
     /// Enable extra validation of get_header responses
-    #[serde(default = "default_bool::<false>")]
-    pub extra_validation_enabled: bool,
+    #[serde(default = "default_header_validation_mode")]
+    pub header_validation_mode: HeaderValidationMode,
+    /// Enable extra validation of submit_block requests
+    #[serde(default = "default_block_validation_mode")]
+    pub block_validation_mode: BlockValidationMode,
     /// Execution Layer RPC url to use for extra validation
     pub rpc_url: Option<Url>,
     /// URL for the user's own SSV node API endpoint
@@ -173,10 +204,10 @@ impl PbsConfig {
             format!("min bid is too high: {} ETH", format_ether(self.min_bid_wei))
         );
 
-        if self.extra_validation_enabled {
+        if self.header_validation_mode == HeaderValidationMode::Extra {
             ensure!(
                 self.rpc_url.is_some(),
-                "rpc_url is required if extra_validation_enabled is true"
+                "rpc_url is required if header_validation_mode is set to extra"
             );
         }
 
@@ -412,6 +443,16 @@ pub async fn load_pbs_custom_config<T: DeserializeOwned>() -> Result<(PbsModuleC
     ))
 }
 
+/// Default value for header validation mode
+fn default_header_validation_mode() -> HeaderValidationMode {
+    HeaderValidationMode::Standard
+}
+
+/// Default value for block validation mode
+fn default_block_validation_mode() -> BlockValidationMode {
+    BlockValidationMode::Standard
+}
+
 /// Default URL for the user's SSV node API endpoint (/v1/validators).
 fn default_ssv_node_api_url() -> Url {
     Url::parse("http://localhost:16000/v1/").expect("default URL is valid")

crates/common/src/config/pbs.rs

@@ -110,3 +110,25 @@ pub enum ValidationError {
     #[error("unsupported fork")]
     UnsupportedFork,
 }
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum SszValueError {
+    #[error("invalid payload length: required {required} but payload was {actual}")]
+    InvalidPayloadLength { required: usize, actual: usize },
+
+    #[error("unsupported fork")]
+    UnsupportedFork { name: String },
+}
+
+impl From<SszValueError> for PbsError {
+    fn from(err: SszValueError) -> Self {
+        match err {
+            SszValueError::InvalidPayloadLength { required, actual } => PbsError::GeneralRequest(
+                format!("invalid payload length: required {required} but payload was {actual}"),
+            ),
+            SszValueError::UnsupportedFork { name } => {
+                PbsError::GeneralRequest(format!("unsupported fork: {name}"))
+            }
+        }
+    }
+}

crates/common/src/pbs/error.rs

@@ -26,22 +26,34 @@ pub type PayloadAndBlobs = lh_eth2::types::ExecutionPayloadAndBlobs<MainnetEthSp
 pub type SubmitBlindedBlockResponse = lh_types::ForkVersionedResponse<PayloadAndBlobs>;
 
 pub type ExecutionPayloadHeader = lh_types::ExecutionPayloadHeader<MainnetEthSpec>;
+pub type ExecutionPayloadHeaderBellatrix =
+    lh_types::ExecutionPayloadHeaderBellatrix<MainnetEthSpec>;
+pub type ExecutionPayloadHeaderCapella = lh_types::ExecutionPayloadHeaderCapella<MainnetEthSpec>;
+pub type ExecutionPayloadHeaderDeneb = lh_types::ExecutionPayloadHeaderDeneb<MainnetEthSpec>;
 pub type ExecutionPayloadHeaderElectra = lh_types::ExecutionPayloadHeaderElectra<MainnetEthSpec>;
 pub type ExecutionPayloadHeaderFulu = lh_types::ExecutionPayloadHeaderFulu<MainnetEthSpec>;
+pub type ExecutionPayloadHeaderGloas = lh_types::ExecutionPayloadHeaderGloas<MainnetEthSpec>;
 pub type ExecutionPayloadHeaderRef<'a> = lh_types::ExecutionPayloadHeaderRef<'a, MainnetEthSpec>;
 pub type ExecutionPayload = lh_types::ExecutionPayload<MainnetEthSpec>;
 pub type ExecutionPayloadElectra = lh_types::ExecutionPayloadElectra<MainnetEthSpec>;
 pub type ExecutionPayloadFulu = lh_types::ExecutionPayloadFulu<MainnetEthSpec>;
 pub type SignedBuilderBid = lh_types::builder_bid::SignedBuilderBid<MainnetEthSpec>;
 pub type BuilderBid = lh_types::builder_bid::BuilderBid<MainnetEthSpec>;
+pub type BuilderBidBellatrix = lh_types::builder_bid::BuilderBidBellatrix<MainnetEthSpec>;
+pub type BuilderBidCapella = lh_types::builder_bid::BuilderBidCapella<MainnetEthSpec>;
+pub type BuilderBidDeneb = lh_types::builder_bid::BuilderBidDeneb<MainnetEthSpec>;
 pub type BuilderBidElectra = lh_types::builder_bid::BuilderBidElectra<MainnetEthSpec>;
+pub type BuilderBidFulu = lh_types::builder_bid::BuilderBidFulu<MainnetEthSpec>;
+pub type BuilderBidGloas = lh_types::builder_bid::BuilderBidGloas<MainnetEthSpec>;
 
 /// Response object of GET
 /// `/eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}`
 pub type GetHeaderResponse = lh_types::ForkVersionedResponse<SignedBuilderBid>;
 
 pub type KzgCommitments = lh_types::beacon_block_body::KzgCommitments<MainnetEthSpec>;
 
+pub type Uint256 = lh_types::Uint256;
+
 /// Response params of GET
 /// `/eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}`
 #[derive(Debug, Serialize, Deserialize, Clone)]

crates/common/src/pbs/types/mod.rs

@@ -1,7 +1,7 @@
 #[cfg(feature = "testing-flags")]
 use std::cell::Cell;
 use std::{
-    collections::HashSet,
+    collections::{HashMap, HashSet},
     fmt::Display,
     net::Ipv4Addr,
     str::FromStr,
@@ -17,9 +17,10 @@ use axum::{
 use bytes::Bytes;
 use futures::StreamExt;
 use headers_accept::Accept;
+use lazy_static::lazy_static;
 pub use lh_types::ForkName;
 use lh_types::{
-    BeaconBlock,
+    BeaconBlock, Signature,
     test_utils::{SeedableRng, TestRandom, XorShiftRng},
 };
 use rand::{Rng, distr::Alphanumeric};
@@ -29,7 +30,7 @@ use reqwest::{
 };
 use serde::{Serialize, de::DeserializeOwned};
 use serde_json::Value;
-use ssz::{Decode, Encode};
+use ssz::{BYTES_PER_LENGTH_OFFSET, Decode, Encode};
 use thiserror::Error;
 use tracing::Level;
 use tracing_appender::{non_blocking::WorkerGuard, rolling::Rotation};
@@ -42,7 +43,7 @@ use tracing_subscriber::{
 use crate::{
     config::LogsSettings,
     constants::SIGNER_JWT_EXPIRATION,
-    pbs::{HEADER_VERSION_VALUE, SignedBlindedBeaconBlock},
+    pbs::{error::SszValueError, *},
     types::{BlsPublicKey, Chain, Jwt, JwtClaims, ModuleId},
 };
 
@@ -53,6 +54,25 @@ pub const WILDCARD: &str = "*/*";
 const MILLIS_PER_SECOND: u64 = 1_000;
 pub const CONSENSUS_VERSION_HEADER: &str = "Eth-Consensus-Version";
 
+lazy_static! {
+    static ref SSZ_VALUE_OFFSETS_BY_FORK: HashMap<ForkName, usize> = {
+        let mut map: HashMap<ForkName, usize> = HashMap::new();
+        let forks = [
+            ForkName::Bellatrix,
+            ForkName::Capella,
+            ForkName::Deneb,
+            ForkName::Electra,
+            ForkName::Fulu,
+            ForkName::Gloas,
+        ];
+        for fork in forks {
+            let offset = get_ssz_value_offset_for_fork(fork).unwrap(); // If there isn't a supported fork, this needs to be updated prior to release so panicking is fine
+            map.insert(fork, offset);
+        }
+        map
+    };
+}
+
 #[derive(Debug, Error)]
 pub enum ResponseReadError {
     #[error(
@@ -640,6 +660,115 @@ pub fn bls_pubkey_from_hex_unchecked(hex: &str) -> BlsPublicKey {
     bls_pubkey_from_hex(hex).unwrap()
 }
 
+// Get the offset of the message in a SignedBuilderBid SSZ structure
+fn get_ssz_value_offset_for_fork(fork: ForkName) -> Option<usize> {
+    match fork {
+        ForkName::Bellatrix => {
+            // Message goes header -> value -> pubkey
+            Some(
+                get_message_offset::<BuilderBidBellatrix>() +
+                    <ExecutionPayloadHeaderBellatrix as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+
+        ForkName::Capella => {
+            // Message goes header -> value -> pubkey
+            Some(
+                get_message_offset::<BuilderBidCapella>() +
+                    <ExecutionPayloadHeaderCapella as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+
+        ForkName::Deneb => {
+            // Message goes header -> blob_kzg_commitments -> value -> pubkey
+            Some(
+                get_message_offset::<BuilderBidDeneb>() +
+                    <ExecutionPayloadHeaderDeneb as ssz::Decode>::ssz_fixed_len() +
+                    <KzgCommitments as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+
+        ForkName::Electra => {
+            // Message goes header -> blob_kzg_commitments -> execution_requests -> value ->
+            // pubkey
+            Some(
+                get_message_offset::<BuilderBidElectra>() +
+                    <ExecutionPayloadHeaderElectra as ssz::Decode>::ssz_fixed_len() +
+                    <KzgCommitments as ssz::Decode>::ssz_fixed_len() +
+                    <ExecutionRequests as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+
+        ForkName::Fulu => {
+            // Message goes header -> blob_kzg_commitments -> execution_requests -> value ->
+            // pubkey
+            Some(
+                get_message_offset::<BuilderBidFulu>() +
+                    <ExecutionPayloadHeaderFulu as ssz::Decode>::ssz_fixed_len() +
+                    <KzgCommitments as ssz::Decode>::ssz_fixed_len() +
+                    <ExecutionRequests as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+
+        ForkName::Gloas => {
+            // Message goes header -> blob_kzg_commitments -> execution_requests -> value ->
+            // pubkey
+            Some(
+                get_message_offset::<BuilderBidGloas>() +
+                    <ExecutionPayloadHeaderGloas as ssz::Decode>::ssz_fixed_len() +
+                    <KzgCommitments as ssz::Decode>::ssz_fixed_len() +
+                    <ExecutionRequests as ssz::Decode>::ssz_fixed_len(),
+            )
+        }
+        _ => None,
+    }
+}
+
+/// Extracts the bid value from SSZ-encoded SignedBuilderBid response bytes.
+pub fn get_bid_value_from_signed_builder_bid_ssz(
+    response_bytes: &[u8],
+    fork: ForkName,
+) -> Result<U256, SszValueError> {
+    let value_offset = SSZ_VALUE_OFFSETS_BY_FORK
+        .get(&fork)
+        .ok_or(SszValueError::UnsupportedFork { name: fork.to_string() })?;
+
+    // Sanity check the response length so we don't panic trying to slice it
+    let end_offset = value_offset + 32; // U256 is 32 bytes
+    if response_bytes.len() < end_offset {
+        return Err(SszValueError::InvalidPayloadLength {
+            required: end_offset,
+            actual: response_bytes.len(),
+        });
+    }
+
+    // Extract the value bytes and convert to U256
+    let value_bytes = &response_bytes[*value_offset..end_offset];
+    let value = U256::from_le_slice(value_bytes);
+    Ok(value)
+}
+
+// Get the offset where the `message` field starts in some SignedBuilderBid SSZ
+// data. Requires that SignedBuilderBid always has the following structure:
+// message -> signature
+// where `message` is a BuilderBid type determined by the fork choice, and
+// `signature` is a fixed-length Signature type.
+fn get_message_offset<BuilderBidType>() -> usize
+where
+    BuilderBidType: ssz::Encode,
+{
+    // Since `message` is the first field, its offset is always 0
+    let mut offset = 0;
+
+    // If it's variable length, then it will be represented by a pointer to
+    // the actual data, so we need to get the location of where that data starts
+    if !BuilderBidType::is_ssz_fixed_len() {
+        offset += BYTES_PER_LENGTH_OFFSET + <Signature as ssz::Decode>::ssz_fixed_len();
+    }
+
+    offset
+}
+
 #[cfg(test)]
 mod test {
     use axum::http::{HeaderMap, HeaderValue};

crates/common/src/utils.rs

@@ -12,11 +12,13 @@ axum.workspace = true
 axum-extra.workspace = true
 cb-common.workspace = true
 cb-metrics.workspace = true
+ethereum_serde_utils.workspace = true
 ethereum_ssz.workspace = true
 eyre.workspace = true
 futures.workspace = true
 headers.workspace = true
 lazy_static.workspace = true
+lh_types.workspace = true
 notify.workspace = true
 parking_lot.workspace = true
 prometheus.workspace = true