quorum-sdk 0.1.0

Official Rust SDK for Quorum routing intelligence on Solana
Documentation
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Objective {
    Fastest,
    HighestLanding,
    LowestFee,
    MevProtected,
}

impl Objective {
    pub fn as_str(&self) -> &'static str {
        match self {
            Objective::Fastest => "fastest",
            Objective::HighestLanding => "highest_landing",
            Objective::LowestFee => "lowest_fee",
            Objective::MevProtected => "mev_protected",
        }
    }
}

impl std::fmt::Display for Objective {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl std::str::FromStr for Objective {
    type Err = crate::QuorumError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "fastest" => Ok(Objective::Fastest),
            "highest_landing" | "highestlanding" => Ok(Objective::HighestLanding),
            "lowest_fee" | "lowestfee" => Ok(Objective::LowestFee),
            "mev_protected" | "mevprotected" => Ok(Objective::MevProtected),
            other => Err(crate::QuorumError::InvalidResponse(format!(
                "unknown objective: {}",
                other
            ))),
        }
    }
}

impl Serialize for Objective {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for Objective {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}

#[derive(Debug, Serialize)]
pub(crate) struct ExecuteRequest {
    pub wire_transaction_b64: String,
    pub objective: Objective,
}

#[derive(Debug, Clone, Deserialize)]
pub struct ExecutionResult {
    #[serde(alias = "success", default)]
    pub landed: bool,
    pub signature: Option<String>,
    #[serde(alias = "route_used")]
    pub route_type: Option<String>,
    pub latency_ms: Option<u64>,
    #[serde(default)]
    pub attempts: usize,
    pub request_id: Option<String>,
    pub validator: Option<String>,
    pub tpu_addr: Option<String>,
    pub confirmation_ms: Option<u64>,
    pub fee_paid: Option<u64>,
    pub predicted_probability: Option<f64>,
    pub error: Option<String>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Route {
    #[serde(rename = "type")]
    pub route_type: Option<String>,
    pub validator: Option<String>,
    pub tpu_addr: Option<String>,
    pub latency_ms: Option<u64>,
    pub score: Option<f64>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct PrimaryRoute {
    #[serde(rename = "type")]
    pub mode: Option<String>,
    #[serde(default)]
    pub routes: Vec<Route>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct FallbackRoute {
    #[serde(rename = "type")]
    pub route_type: Option<String>,
    pub endpoint: Option<String>,
    pub validator: Option<String>,
    pub tpu_addr: Option<String>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Strategy {
    pub objective: String,
    pub primary: Option<PrimaryRoute>,
    #[serde(default)]
    pub fallbacks: Vec<FallbackRoute>,
    pub landing_probability: f64,
    pub recommended_fee_microlamports: u64,
    pub ttl_secs: Option<u64>,
    pub computed_at: Option<String>,
    pub validator: Option<String>,
    pub tpu_addr: Option<String>,
    pub latency_ms: Option<u64>,
}

impl Strategy {
    pub fn primary_leader(&self) -> Option<&Route> {
        self.primary.as_ref().and_then(|p| p.routes.first())
    }

    pub fn primary_validator(&self) -> Option<&str> {
        self.primary_leader()
            .and_then(|r| r.validator.as_deref())
            .or(self.validator.as_deref())
    }

    pub fn primary_tpu_addr(&self) -> Option<&str> {
        self.primary_leader()
            .and_then(|r| r.tpu_addr.as_deref())
            .or(self.tpu_addr.as_deref())
    }

    pub fn primary_latency_ms(&self) -> Option<u64> {
        self.primary_leader()
            .and_then(|r| r.latency_ms)
            .or(self.latency_ms)
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct ValidatorInfo {
    pub pubkey: String,
    pub latency_ms: Option<u64>,
    pub score: f64,
    #[serde(default)]
    pub reachable: bool,
    #[serde(alias = "client_type")]
    pub client: Option<String>,
    pub tpu_addr: Option<String>,
    #[serde(default)]
    pub observer_count: Option<u32>,
    #[serde(default)]
    pub supports_bundles: Option<bool>,
    #[serde(default)]
    pub computed_at: Option<String>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct CongestionSignal {
    #[serde(alias = "congestion_level", default)]
    pub congestion_level: f64,
    #[serde(default)]
    pub fee_multiplier: Option<f64>,
    #[serde(default)]
    pub unreachable_ratio: Option<f64>,
    #[serde(default)]
    pub mean_latency_ms: Option<u64>,
    #[serde(default)]
    pub timestamp: Option<String>,
    #[serde(default)]
    pub level: Option<String>,
    #[serde(default)]
    pub recommended_fee_microlamports: Option<u64>,
    #[serde(default)]
    pub slot_fill_rate: Option<f64>,
    #[serde(default)]
    pub drop_rate: Option<f64>,
    #[serde(default)]
    pub updated_at: Option<u64>,
}

impl CongestionSignal {
    pub fn level_str(&self) -> &str {
        if let Some(ref l) = self.level {
            return l.as_str();
        }
        if self.congestion_level < 0.25 {
            "low"
        } else if self.congestion_level < 0.60 {
            "medium"
        } else if self.congestion_level < 0.85 {
            "high"
        } else {
            "critical"
        }
    }

    pub fn fee_recommendation(&self) -> u64 {
        if let Some(fee) = self.recommended_fee_microlamports {
            return fee;
        }
        if let Some(mult) = self.fee_multiplier {
            return (mult * 5000.0) as u64;
        }
        5000
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct HealthStatus {
    pub status: String,
    pub version: Option<String>,
    #[serde(default)]
    pub ready: bool,
    #[serde(alias = "validators_scored", default)]
    pub validators_tracked: usize,
    pub congestion_level: Option<f64>,
    pub last_updated: Option<String>,
    pub last_sweep_id: Option<u64>,
}