khadhroony-solana-project/crates/ksp-onchain-transport-lib/src/rpc_canary.rs

// file: crates/ksp-onchain-transport-lib/src/rpc_canary.rs
// version: 1

/// Commitment level accepted by the initial typed Solana HTTP canary adapters.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum SolanaCommitment {
    /// Query the most recent processed bank.
    Processed,
    /// Query a bank confirmed by cluster vote.
    Confirmed,
    /// Query a finalized bank.
    Finalized,
}

impl SolanaCommitment {
    /// Returns the Solana JSON-RPC commitment string.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        return match self {
            Self::Processed => "processed",
            Self::Confirmed => "confirmed",
            Self::Finalized => "finalized",
        };
    }
}

/// Optional typed configuration for `getBalance`.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct GetBalanceConfig {
    commitment: std::option::Option<crate::SolanaCommitment>,
    min_context_slot: std::option::Option<u64>,
}

impl GetBalanceConfig {
    /// Creates an explicit `getBalance` configuration.
    #[must_use]
    pub const fn new(commitment: std::option::Option<crate::SolanaCommitment>, min_context_slot: std::option::Option<u64>) -> Self {
        return Self { commitment, min_context_slot };
    }

    /// Returns the optional commitment level.
    #[must_use]
    pub const fn commitment(&self) -> std::option::Option<crate::SolanaCommitment> {
        return self.commitment;
    }

    /// Returns the optional minimum context slot.
    #[must_use]
    pub const fn min_context_slot(&self) -> std::option::Option<u64> {
        return self.min_context_slot;
    }

    fn is_empty(&self) -> bool {
        return self.commitment.is_none() && self.min_context_slot.is_none();
    }

    fn to_json_value(&self) -> serde_json::Value {
        let mut object = serde_json::Map::new();
        if let std::option::Option::Some(commitment) = self.commitment {
            object.insert("commitment".to_owned(), serde_json::Value::String(commitment.as_str().to_owned()));
        }
        if let std::option::Option::Some(min_context_slot) = self.min_context_slot {
            object.insert("minContextSlot".to_owned(), serde_json::Value::Number(min_context_slot.into()));
        }
        return serde_json::Value::Object(object);
    }
}

/// Typed healthy result returned by the `getHealth` canary.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum SolanaNodeHealth {
    /// The RPC node returned the stable `"ok"` health result.
    Healthy,
}

/// Typed genesis hash returned by the `getGenesisHash` canary.
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct SolanaGenesisHash {
    value: std::string::String,
}

impl SolanaGenesisHash {
    /// Returns the base58-encoded genesis hash text.
    #[must_use]
    pub fn as_str(&self) -> &str {
        return self.value.as_str();
    }
}

/// Typed software-version response returned by the `getVersion` canary.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SolanaNodeVersion {
    solana_core: std::string::String,
    feature_set: std::option::Option<u32>,
}

impl SolanaNodeVersion {
    /// Returns the node software version string from the `solana-core` field.
    #[must_use]
    pub fn solana_core(&self) -> &str {
        return self.solana_core.as_str();
    }

    /// Returns the optional runtime feature-set identifier.
    #[must_use]
    pub const fn feature_set(&self) -> std::option::Option<u32> {
        return self.feature_set;
    }
}

/// Typed Solana RPC context used by the initial account canary.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SolanaRpcContext {
    slot: u64,
    api_version: std::option::Option<std::string::String>,
}

impl SolanaRpcContext {
    /// Returns the context slot reported by the RPC node.
    #[must_use]
    pub const fn slot(&self) -> u64 {
        return self.slot;
    }

    /// Returns the optional RPC API version reported by the node.
    #[must_use]
    pub fn api_version(&self) -> std::option::Option<&str> {
        return match self.api_version.as_ref() {
            std::option::Option::Some(value) => std::option::Option::Some(value.as_str()),
            std::option::Option::None => std::option::Option::None,
        };
    }
}

/// Typed lamport balance returned by the `getBalance` canary.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct GetBalanceResult {
    context: crate::SolanaRpcContext,
    value: u64,
}

impl GetBalanceResult {
    /// Returns the Solana response context.
    #[must_use]
    pub const fn context(&self) -> &crate::SolanaRpcContext {
        return &self.context;
    }

    /// Returns the account balance in lamports.
    #[must_use]
    pub const fn value(&self) -> u64 {
        return self.value;
    }
}

impl crate::HttpTransportPool {
    /// Executes the typed `getHealth` foundation canary.
    pub async fn get_health(&self, role: &crate::HttpRoleName) -> ksp_core_lib::Result<crate::SolanaNodeHealth> {
        let method_result = canary_descriptor("getHealth");
        let method = match method_result {
            std::result::Result::Ok(method) => method,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let result = self.execute_standard_rpc(role, method, std::vec::Vec::new()).await;
        let value = match result {
            std::result::Result::Ok(value) => value,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        if value.as_str() == std::option::Option::Some("ok") {
            return std::result::Result::Ok(crate::SolanaNodeHealth::Healthy);
        }
        return invalid_canary_response("getHealth", "result must be exactly the string ok");
    }

    /// Executes the typed `getGenesisHash` foundation canary.
    pub async fn get_genesis_hash(&self, role: &crate::HttpRoleName) -> ksp_core_lib::Result<crate::SolanaGenesisHash> {
        let method_result = canary_descriptor("getGenesisHash");
        let method = match method_result {
            std::result::Result::Ok(method) => method,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let result = self.execute_standard_rpc(role, method, std::vec::Vec::new()).await;
        let value = match result {
            std::result::Result::Ok(value) => value,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let hash = match value.as_str() {
            std::option::Option::Some(hash) => hash,
            std::option::Option::None => return invalid_canary_response("getGenesisHash", "result must be a string"),
        };
        if hash.is_empty() || hash.trim() != hash {
            return invalid_canary_response("getGenesisHash", "result must be a non-empty trimmed string");
        }
        return std::result::Result::Ok(crate::SolanaGenesisHash { value: hash.to_owned() });
    }

    /// Executes the typed `getVersion` foundation canary.
    pub async fn get_version(&self, role: &crate::HttpRoleName) -> ksp_core_lib::Result<crate::SolanaNodeVersion> {
        let method_result = canary_descriptor("getVersion");
        let method = match method_result {
            std::result::Result::Ok(method) => method,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let result = self.execute_standard_rpc(role, method, std::vec::Vec::new()).await;
        let value = match result {
            std::result::Result::Ok(value) => value,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let decode_result = serde_json::from_value::<WireNodeVersion>(value);
        let decoded = match decode_result {
            std::result::Result::Ok(decoded) => decoded,
            std::result::Result::Err(error) => return invalid_canary_decode("getVersion", error),
        };
        if decoded.solana_core.is_empty() || decoded.solana_core.trim() != decoded.solana_core {
            return invalid_canary_response("getVersion", "solana-core must be a non-empty trimmed string");
        }
        return std::result::Result::Ok(crate::SolanaNodeVersion { solana_core: decoded.solana_core, feature_set: decoded.feature_set });
    }

    /// Executes the typed `getBalance` foundation canary.
    pub async fn get_balance(
        &self,
        role: &crate::HttpRoleName,
        account: &ksp_core_lib::Pubkey,
        config: std::option::Option<&crate::GetBalanceConfig>,
    ) -> ksp_core_lib::Result<crate::GetBalanceResult> {
        let method_result = canary_descriptor("getBalance");
        let method = match method_result {
            std::result::Result::Ok(method) => method,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let mut params = std::vec![serde_json::Value::String(account.to_string())];
        if let std::option::Option::Some(config) = config
            && !config.is_empty()
        {
            params.push(config.to_json_value());
        }
        let result = self.execute_standard_rpc(role, method, params).await;
        let value = match result {
            std::result::Result::Ok(value) => value,
            std::result::Result::Err(error) => return std::result::Result::Err(error),
        };
        let decode_result = serde_json::from_value::<WireBalanceResult>(value);
        let decoded = match decode_result {
            std::result::Result::Ok(decoded) => decoded,
            std::result::Result::Err(error) => return invalid_canary_decode("getBalance", error),
        };
        return std::result::Result::Ok(crate::GetBalanceResult {
            context: crate::SolanaRpcContext { slot: decoded.context.slot, api_version: decoded.context.api_version },
            value: decoded.value,
        });
    }
}

#[derive(serde::Deserialize)]
struct WireNodeVersion {
    #[serde(rename = "solana-core")]
    solana_core: std::string::String,
    #[serde(rename = "feature-set", default)]
    feature_set: std::option::Option<u32>,
}

#[derive(serde::Deserialize)]
struct WireRpcContext {
    slot: u64,
    #[serde(rename = "apiVersion", default)]
    api_version: std::option::Option<std::string::String>,
}

#[derive(serde::Deserialize)]
struct WireBalanceResult {
    context: WireRpcContext,
    value: u64,
}

fn canary_descriptor(method: &str) -> ksp_core_lib::Result<&'static crate::HttpRpcMethodDescriptor> {
    let descriptor = crate::find_http_rpc_method(method);
    return match descriptor {
        std::option::Option::Some(descriptor) => std::result::Result::Ok(descriptor),
        std::option::Option::None => std::result::Result::Err(
            ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "typed canary descriptor is missing from the audited registry")
                .with_context("rpc_method", method),
        ),
    };
}

fn invalid_canary_decode<T>(method: &str, error: serde_json::Error) -> ksp_core_lib::Result<T> {
    return std::result::Result::Err(
        ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, "typed Solana HTTP canary response has an invalid shape")
            .with_context("rpc_method", method)
            .with_source(error),
    );
}

fn invalid_canary_response<T>(method: &str, message: &str) -> ksp_core_lib::Result<T> {
    return std::result::Result::Err(ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_RESPONSE, message).with_context("rpc_method", method));
}

#[cfg(test)]
#[path = "../unit_tests/rpc_canary.rs"]
mod tests;