coldstar_network/

lib.rs

//! Full Solana RPC client for Coldstar cold wallet.
//!
//! Ported from the Python `src/network.py` in `coldstar-devsyrem`.
//! Uses `reqwest::blocking` with JSON-RPC 2.0 format for all Solana
//! RPC interactions.

pub mod token;

use std::thread;
use std::time::Duration;

use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use thiserror::Error;

use coldstar_config::{ColdstarConfig, LAMPORTS_PER_SOL};

// ---------------------------------------------------------------------------
// Error types
// ---------------------------------------------------------------------------

/// Errors that can occur during RPC operations.
#[derive(Debug, Error)]
pub enum RpcError {
    /// HTTP transport error.
    #[error("HTTP error: {0}")]
    Http(#[from] reqwest::Error),

    /// The RPC endpoint returned a JSON-RPC error object.
    #[error("RPC error {code}: {message}")]
    Rpc { code: i64, message: String },

    /// The response JSON could not be parsed or was missing expected fields.
    #[error("Invalid response: {0}")]
    InvalidResponse(String),

    /// The provided RPC URL failed validation.
    #[error("Invalid RPC URL: {0}")]
    InvalidUrl(String),

    /// The provided Solana address is malformed.
    #[error("Invalid address: {0}")]
    InvalidAddress(String),

    /// A transaction confirmation timed out.
    #[error("Transaction confirmation timed out after {0}s")]
    Timeout(u64),

    /// Serialization / deserialization error.
    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),
}

/// Convenience alias used throughout this crate.
pub type Result<T> = std::result::Result<T, RpcError>;

// ---------------------------------------------------------------------------
// Data types
// ---------------------------------------------------------------------------

/// On-chain account information returned by `getAccountInfo`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AccountInfo {
    /// Account balance in lamports.
    pub lamports: u64,
    /// Account owner program (base-58).
    pub owner: String,
    /// Account data encoded as base-64.
    pub data: String,
    /// Whether the account is executable.
    pub executable: bool,
    /// Epoch at which this account will next owe rent.
    pub rent_epoch: u64,
}

/// High-level network information.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkInfo {
    /// Solana core version string.
    pub version: String,
    /// Current slot.
    pub slot: u64,
    /// Current epoch number.
    pub epoch: u64,
    /// RPC URL that produced this info.
    pub rpc_url: String,
}

/// A single entry from `getSignaturesForAddress`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TransactionRecord {
    /// Transaction signature (base-58).
    pub signature: String,
    /// Slot the transaction was processed in.
    pub slot: u64,
    /// Block time as Unix timestamp (may be absent for very old txns).
    pub block_time: Option<i64>,
    /// Whether the transaction had an error.
    pub err: Option<Value>,
    /// Optional memo string.
    pub memo: Option<String>,
    /// Confirmation status.
    pub confirmation_status: Option<String>,
}

/// Detailed transaction data returned by `getTransaction`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TransactionDetails {
    /// Slot the transaction landed in.
    pub slot: u64,
    /// Block time as Unix timestamp.
    pub block_time: Option<i64>,
    /// The full transaction JSON (jsonParsed encoding).
    pub transaction: Value,
    /// Transaction metadata (fee, balances, logs, etc.).
    pub meta: Option<Value>,
}

// ---------------------------------------------------------------------------
// SolanaRpcClient
// ---------------------------------------------------------------------------

/// Blocking Solana JSON-RPC 2.0 client.
///
/// Mirrors the Python `SolanaNetwork` class from `coldstar-devsyrem`.
#[derive(Debug)]
pub struct SolanaRpcClient {
    rpc_url: String,
    client: reqwest::blocking::Client,
}

impl SolanaRpcClient {
    // ── Constructor ──────────────────────────────────────────────────

    /// Create a new client pointing at `rpc_url`.
    ///
    /// The URL must start with `http://` or `https://`. If `None` is
    /// passed the default from [`ColdstarConfig`] is used.
    pub fn new(rpc_url: Option<&str>) -> Result<Self> {
        let url = match rpc_url {
            Some(u) => u.to_string(),
            None => ColdstarConfig::from_env().rpc_url,
        };

        // Validate URL scheme.
        if !url.starts_with("http://") && !url.starts_with("https://") {
            return Err(RpcError::InvalidUrl(
                "URL must start with http:// or https://".into(),
            ));
        }

        // Basic length / content check.
        if url.len() < 10 {
            return Err(RpcError::InvalidUrl("URL is too short".into()));
        }

        let client = reqwest::blocking::Client::builder()
            .timeout(Duration::from_secs(30))
            .build()?;

        Ok(Self {
            rpc_url: url,
            client,
        })
    }

    /// Build a client from an existing [`ColdstarConfig`].
    pub fn from_config(cfg: &ColdstarConfig) -> Result<Self> {
        Self::new(Some(&cfg.rpc_url))
    }

    /// Return the RPC URL this client is connected to.
    pub fn rpc_url(&self) -> &str {
        &self.rpc_url
    }

    /// Expose the underlying blocking HTTP client (used by [`token::TokenFetcher`]).
    pub(crate) fn http_client(&self) -> &reqwest::blocking::Client {
        &self.client
    }

    // ── Low-level JSON-RPC helper ────────────────────────────────────

    /// Send a JSON-RPC 2.0 request and return the raw response [`Value`].
    fn rpc_request(&self, method: &str, params: Value) -> Result<Value> {
        let payload = json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": method,
            "params": params,
        });

        let resp = self
            .client
            .post(&self.rpc_url)
            .header("Content-Type", "application/json")
            .json(&payload)
            .send()?;

        let body: Value = resp.json()?;

        // Check for JSON-RPC error envelope.
        if let Some(err) = body.get("error") {
            let code = err.get("code").and_then(Value::as_i64).unwrap_or(-1);
            let message = err
                .get("message")
                .and_then(Value::as_str)
                .unwrap_or("Unknown RPC error")
                .to_string();
            return Err(RpcError::Rpc { code, message });
        }

        Ok(body)
    }

    // ── Public API ───────────────────────────────────────────────────

    /// Get SOL balance for `pubkey` in **lamports**.
    pub fn get_balance(&self, pubkey: &str) -> Result<u64> {
        validate_address(pubkey)?;

        let body = self.rpc_request("getBalance", json!([pubkey]))?;

        body.get("result")
            .and_then(|r| r.get("value"))
            .and_then(Value::as_u64)
            .ok_or_else(|| RpcError::InvalidResponse("missing result.value".into()))
    }

    /// Get SOL balance for `pubkey` in **SOL** (floating point).
    pub fn get_balance_sol(&self, pubkey: &str) -> Result<f64> {
        let lamports = self.get_balance(pubkey)?;
        Ok(lamports as f64 / LAMPORTS_PER_SOL as f64)
    }

    /// Fetch the latest blockhash and last valid block height.
    pub fn get_latest_blockhash(&self) -> Result<String> {
        let body = self.rpc_request(
            "getLatestBlockhash",
            json!([{"commitment": "finalized"}]),
        )?;

        let value = body
            .get("result")
            .and_then(|r| r.get("value"))
            .ok_or_else(|| RpcError::InvalidResponse("missing result.value".into()))?;

        let blockhash = value
            .get("blockhash")
            .and_then(Value::as_str)
            .ok_or_else(|| RpcError::InvalidResponse("missing blockhash".into()))?;

        // Validate blockhash format (base-58, 32-44 chars).
        if blockhash.len() < 32 || blockhash.len() > 44 {
            return Err(RpcError::InvalidResponse(
                "blockhash has invalid length".into(),
            ));
        }

        Ok(blockhash.to_string())
    }

    /// Fetch the latest blockhash together with the last valid block height.
    pub fn get_latest_blockhash_with_height(&self) -> Result<(String, u64)> {
        let body = self.rpc_request(
            "getLatestBlockhash",
            json!([{"commitment": "finalized"}]),
        )?;

        let value = body
            .get("result")
            .and_then(|r| r.get("value"))
            .ok_or_else(|| RpcError::InvalidResponse("missing result.value".into()))?;

        let blockhash = value
            .get("blockhash")
            .and_then(Value::as_str)
            .ok_or_else(|| RpcError::InvalidResponse("missing blockhash".into()))?
            .to_string();

        let height = value
            .get("lastValidBlockHeight")
            .and_then(Value::as_u64)
            .ok_or_else(|| {
                RpcError::InvalidResponse("missing lastValidBlockHeight".into())
            })?;

        Ok((blockhash, height))
    }

    /// Get the minimum lamport balance required for rent exemption at
    /// `data_len` bytes of account data.
    pub fn get_minimum_balance_for_rent_exemption(&self, data_len: usize) -> Result<u64> {
        let body = self.rpc_request(
            "getMinimumBalanceForRentExemption",
            json!([data_len]),
        )?;

        body.get("result")
            .and_then(Value::as_u64)
            .ok_or_else(|| RpcError::InvalidResponse("missing result".into()))
    }

    /// Broadcast a signed transaction encoded as **base-64**.
    ///
    /// Returns the transaction signature on success.
    pub fn send_transaction(&self, signed_tx_base64: &str) -> Result<String> {
        let body = self.rpc_request(
            "sendTransaction",
            json!([
                signed_tx_base64,
                {"encoding": "base64", "preflightCommitment": "finalized"}
            ]),
        )?;

        body.get("result")
            .and_then(Value::as_str)
            .map(String::from)
            .ok_or_else(|| RpcError::InvalidResponse("missing result signature".into()))
    }

    /// Poll `getSignatureStatuses` until the transaction reaches
    /// `confirmed` or `finalized`, or the timeout elapses.
    ///
    /// `timeout_secs` defaults to 30 if set to 0.
    pub fn confirm_transaction(&self, signature: &str, timeout_secs: u64) -> Result<bool> {
        let timeout = if timeout_secs == 0 { 30 } else { timeout_secs };
        let deadline = std::time::Instant::now() + Duration::from_secs(timeout);

        while std::time::Instant::now() < deadline {
            match self.rpc_request("getSignatureStatuses", json!([[signature]])) {
                Ok(body) => {
                    if let Some(statuses) = body
                        .get("result")
                        .and_then(|r| r.get("value"))
                        .and_then(Value::as_array)
                    {
                        if let Some(status) = statuses.first().and_then(Value::as_object) {
                            // Check for transaction-level error.
                            if status.get("err").is_some()
                                && !status["err"].is_null()
                            {
                                return Ok(false);
                            }
                            if let Some(cs) =
                                status.get("confirmationStatus").and_then(Value::as_str)
                            {
                                if cs == "confirmed" || cs == "finalized" {
                                    return Ok(true);
                                }
                            }
                        }
                    }
                }
                Err(_) => { /* retry */ }
            }
            thread::sleep(Duration::from_secs(1));
        }

        Err(RpcError::Timeout(timeout))
    }

    /// Request an airdrop of `lamports` to `pubkey` (devnet/testnet only).
    ///
    /// Returns the airdrop transaction signature.
    pub fn request_airdrop(&self, pubkey: &str, lamports: u64) -> Result<String> {
        validate_address(pubkey)?;

        let body = self.rpc_request("requestAirdrop", json!([pubkey, lamports]))?;

        body.get("result")
            .and_then(Value::as_str)
            .map(String::from)
            .ok_or_else(|| RpcError::InvalidResponse("missing airdrop signature".into()))
    }

    /// Get on-chain account information for `pubkey`.
    ///
    /// Returns `None` when the account does not exist.
    pub fn get_account_info(&self, pubkey: &str) -> Result<Option<AccountInfo>> {
        validate_address(pubkey)?;

        let body = self.rpc_request(
            "getAccountInfo",
            json!([pubkey, {"encoding": "base64"}]),
        )?;

        let value = body
            .get("result")
            .and_then(|r| r.get("value"));

        match value {
            Some(v) if !v.is_null() => {
                let lamports = v.get("lamports").and_then(Value::as_u64).unwrap_or(0);
                let owner = v
                    .get("owner")
                    .and_then(Value::as_str)
                    .unwrap_or("")
                    .to_string();
                let data = v
                    .get("data")
                    .and_then(Value::as_array)
                    .and_then(|a| a.first())
                    .and_then(Value::as_str)
                    .unwrap_or("")
                    .to_string();
                let executable = v
                    .get("executable")
                    .and_then(Value::as_bool)
                    .unwrap_or(false);
                let rent_epoch = v.get("rentEpoch").and_then(Value::as_u64).unwrap_or(0);

                Ok(Some(AccountInfo {
                    lamports,
                    owner,
                    data,
                    executable,
                    rent_epoch,
                }))
            }
            _ => Ok(None),
        }
    }

    /// Check whether the RPC endpoint is healthy.
    pub fn is_connected(&self) -> bool {
        match self.rpc_request("getHealth", json!([])) {
            Ok(body) => body
                .get("result")
                .and_then(Value::as_str)
                .map(|s| s == "ok")
                .unwrap_or(false),
            Err(_) => false,
        }
    }

    /// Collect high-level network information (version, slot, epoch).
    pub fn get_network_info(&self) -> Result<NetworkInfo> {
        let version_body = self.rpc_request("getVersion", json!([]))?;
        let slot_body = self.rpc_request("getSlot", json!([]))?;
        let epoch_body = self.rpc_request("getEpochInfo", json!([]))?;

        let version = version_body
            .get("result")
            .and_then(|r| r.get("solana-core"))
            .and_then(Value::as_str)
            .unwrap_or("Unknown")
            .to_string();

        let slot = slot_body
            .get("result")
            .and_then(Value::as_u64)
            .unwrap_or(0);

        let epoch = epoch_body
            .get("result")
            .and_then(|r| r.get("epoch"))
            .and_then(Value::as_u64)
            .unwrap_or(0);

        Ok(NetworkInfo {
            version,
            slot,
            epoch,
            rpc_url: self.rpc_url.clone(),
        })
    }

    /// Get recent transaction signatures for `pubkey`.
    pub fn get_transaction_history(
        &self,
        pubkey: &str,
        limit: usize,
    ) -> Result<Vec<TransactionRecord>> {
        validate_address(pubkey)?;

        let body = self.rpc_request(
            "getSignaturesForAddress",
            json!([pubkey, {"limit": limit}]),
        )?;

        let entries = body
            .get("result")
            .and_then(Value::as_array)
            .ok_or_else(|| RpcError::InvalidResponse("missing result array".into()))?;

        let mut records = Vec::with_capacity(entries.len());
        for entry in entries {
            records.push(TransactionRecord {
                signature: entry
                    .get("signature")
                    .and_then(Value::as_str)
                    .unwrap_or("")
                    .to_string(),
                slot: entry.get("slot").and_then(Value::as_u64).unwrap_or(0),
                block_time: entry.get("blockTime").and_then(Value::as_i64),
                err: entry.get("err").cloned(),
                memo: entry
                    .get("memo")
                    .and_then(Value::as_str)
                    .map(String::from),
                confirmation_status: entry
                    .get("confirmationStatus")
                    .and_then(Value::as_str)
                    .map(String::from),
            });
        }

        Ok(records)
    }

    /// Get full details for a single transaction by signature.
    pub fn get_transaction_details(&self, signature: &str) -> Result<TransactionDetails> {
        let body = self.rpc_request(
            "getTransaction",
            json!([
                signature,
                {"encoding": "jsonParsed", "maxSupportedTransactionVersion": 0}
            ]),
        )?;

        let result = body
            .get("result")
            .ok_or_else(|| RpcError::InvalidResponse("missing result".into()))?;

        if result.is_null() {
            return Err(RpcError::InvalidResponse(
                "transaction not found".into(),
            ));
        }

        Ok(TransactionDetails {
            slot: result.get("slot").and_then(Value::as_u64).unwrap_or(0),
            block_time: result.get("blockTime").and_then(Value::as_i64),
            transaction: result
                .get("transaction")
                .cloned()
                .unwrap_or(Value::Null),
            meta: result.get("meta").cloned(),
        })
    }
}

// ---------------------------------------------------------------------------
// Validation helpers
// ---------------------------------------------------------------------------

/// Validate that `address` looks like a valid Solana base-58 public key.
pub(crate) fn validate_address(address: &str) -> Result<()> {
    if address.is_empty() {
        return Err(RpcError::InvalidAddress("address is empty".into()));
    }
    if address.len() < 32 || address.len() > 44 {
        return Err(RpcError::InvalidAddress(format!(
            "expected 32-44 chars, got {}",
            address.len()
        )));
    }
    // Base-58 character set (no 0, O, I, l).
    if !address
        .chars()
        .all(|c| c.is_ascii_alphanumeric() && c != '0' && c != 'O' && c != 'I' && c != 'l')
    {
        return Err(RpcError::InvalidAddress(
            "contains invalid base-58 characters".into(),
        ));
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rejects_invalid_url_no_scheme() {
        let err = SolanaRpcClient::new(Some("not-a-url")).unwrap_err();
        assert!(matches!(err, RpcError::InvalidUrl(_)));
    }

    #[test]
    fn rejects_short_url() {
        let err = SolanaRpcClient::new(Some("http://x")).unwrap_err();
        assert!(matches!(err, RpcError::InvalidUrl(_)));
    }

    #[test]
    fn accepts_valid_devnet_url() {
        let client = SolanaRpcClient::new(Some("https://api.devnet.solana.com")).unwrap();
        assert_eq!(client.rpc_url(), "https://api.devnet.solana.com");
    }

    #[test]
    fn uses_config_default_when_none() {
        let client = SolanaRpcClient::new(None).unwrap();
        // Should resolve to the default from ColdstarConfig (devnet).
        assert!(client.rpc_url().contains("solana.com"));
    }

    #[test]
    fn validate_address_ok() {
        // Well-known system program address.
        assert!(validate_address("11111111111111111111111111111111").is_ok());
    }

    #[test]
    fn validate_address_empty() {
        assert!(validate_address("").is_err());
    }

    #[test]
    fn validate_address_too_short() {
        assert!(validate_address("abc").is_err());
    }

    #[test]
    fn validate_address_bad_chars() {
        // 'O' is not valid base-58.
        assert!(validate_address("OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO").is_err());
    }

    #[test]
    fn network_info_struct_serializes() {
        let info = NetworkInfo {
            version: "1.18.0".into(),
            slot: 123456,
            epoch: 42,
            rpc_url: "https://api.devnet.solana.com".into(),
        };
        let json = serde_json::to_string(&info).unwrap();
        assert!(json.contains("1.18.0"));
    }
}