lightspeed_sdk/

client.rs

// src/client.rs
#![allow(deprecated)]

use crate::{LightspeedConfig, LightspeedError, Priority, TransactionResult};
use solana_sdk::{
    instruction::Instruction,
    pubkey::Pubkey,
    signature::Signature,
    system_instruction,
    transaction::Transaction,
    signer::Signer,
};
use std::str::FromStr;
use std::sync::Arc;
use tokio::sync::Mutex;
use url::Url;
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};

/// Lightspeed tip recipient address
/// 
/// All tip transactions are sent to this address to enable prioritized processing.
pub const LIGHTSPEED_TIP_ADDRESS: &str = "53PhM3UTdMQWu5t81wcd35AHGc5xpmHoRjem7GQPvXjA";

/// Minimum tip amount in lamports (0.0001 SOL)
/// 
/// Transactions with tips below this amount will be rejected to ensure
/// meaningful prioritization.
pub const MIN_TIP_LAMPORTS: u64 = 100_000;

/// Lightspeed RPC client for prioritized transaction processing
/// 
/// The client handles authentication, tip management, and connection maintenance
/// for interacting with the Lightspeed service. API keys are securely transmitted
/// via the Authorization header on all requests.
/// 
/// ## Example
/// 
/// ```rust
/// use lightspeed_sdk::{LightspeedClientBuilder, Priority};
/// use solana_sdk::{signature::Keypair, signer::Signer};
/// 
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let client = LightspeedClientBuilder::new("your-api-key")
///     .svs_rpc_url("https://basic.rpc.solanavibestation.com") 
///     .build()?;
/// 
/// // Send a transaction with automatic tip injection
/// let payer = Keypair::new();
/// // ... create instructions ...
/// # Ok(())
/// # }
/// ```
pub struct LightspeedClient {
    pub(crate) config: LightspeedConfig,
    http_client: reqwest::Client,
    endpoint: Url,
    tip_pubkey: Pubkey,
    keep_alive_handle: Arc<Mutex<Option<tokio::task::JoinHandle<()>>>>,
}

impl LightspeedClient {
    /// Creates a new Lightspeed client with the provided configuration
    /// 
    /// ## Arguments
    /// 
    /// * `config` - Client configuration including API key, tier, and settings
    /// 
    /// ## Errors
    ///
    /// Returns an error if:
    /// - The API key is empty
    /// - The endpoint URL is invalid
    /// - HTTP client initialization fails
    pub fn new(config: LightspeedConfig) -> Result<Self, LightspeedError> {
        if config.api_key.is_empty() {
            return Err(LightspeedError::InvalidApiKey);
        }

        // Get the endpoint URL from config (handles both custom and SVS URLs)
        let endpoint = config.get_endpoint()?;

        let tip_pubkey = Pubkey::from_str(LIGHTSPEED_TIP_ADDRESS)
            .expect("Invalid tip address constant");

        // Configure HTTP client with authentication headers
        let mut headers = reqwest::header::HeaderMap::new();
        headers.insert(
            reqwest::header::AUTHORIZATION,
            reqwest::header::HeaderValue::from_str(&config.api_key)
                .map_err(|_| LightspeedError::InvalidApiKey)?
        );
        headers.insert(
            reqwest::header::CONTENT_TYPE,
            reqwest::header::HeaderValue::from_static("application/json")
        );
        headers.insert(
            reqwest::header::USER_AGENT,
            reqwest::header::HeaderValue::from_static("lightspeed-sdk-rust/0.1.0")
        );

        let http_client = reqwest::Client::builder()
            .default_headers(headers)
            .timeout(config.timeout)
            .build()?;

        if config.debug {
            log::debug!("Lightspeed endpoint configured: {}", endpoint);
        }

        Ok(Self {
            config,
            http_client,
            endpoint,
            tip_pubkey,
            keep_alive_handle: Arc::new(Mutex::new(None)),
        })
    }
    
    /// Starts automatic keep-alive to maintain connection health
    /// 
    /// Spawns a background task that periodically sends keep-alive requests
    /// to prevent connection timeouts. The interval is configured via
    /// `LightspeedClientBuilder::keep_alive_interval()`.
    /// 
    /// ## Example
    /// 
    /// ```rust
    /// # async fn example(client: lightspeed_sdk::LightspeedClient) -> Result<(), Box<dyn std::error::Error>> {
    /// client.start_keep_alive().await?;
    /// // Connection will be maintained automatically
    /// # Ok(())
    /// # }
    /// ```
    /// 
    /// ## Errors
    /// 
    /// Returns `LightspeedError::KeepAliveAlreadyRunning` if keep-alive is already active.
    pub async fn start_keep_alive(&self) -> Result<(), LightspeedError> {
        let mut handle_guard = self.keep_alive_handle.lock().await;
        
        if handle_guard.is_some() {
            if self.config.debug {
                log::debug!("Keep-alive already running");
            }
            return Err(LightspeedError::KeepAliveAlreadyRunning);
        }
        
        let client = self.clone_for_keep_alive();
        let interval_duration = self.config.keep_alive_interval;

        let task = tokio::spawn(async move {
            let mut interval = tokio::time::interval(interval_duration);
            loop {
                interval.tick().await;
                if let Err(e) = client.keep_alive().await {
                    log::warn!("Keep-alive failed: {:?}", e);
                }
            }
        });

        *handle_guard = Some(task);
        
        if self.config.debug {
            log::debug!("Keep-alive task started with interval {:?}", interval_duration);
        }
        
        Ok(())
    }

    /// Sends a transaction with automatic tip injection using the default priority
    /// 
    /// A tip instruction is automatically appended to your transaction to ensure
    /// prioritized processing. The tip amount is determined by the client's
    /// default priority setting.
    /// 
    /// ## Arguments
    /// 
    /// * `instructions` - Transaction instructions to execute
    /// * `payer` - Account paying for transaction fees and tip
    /// * `signers` - All required transaction signers
    /// * `recent_blockhash` - Recent blockhash from the cluster
    /// 
    /// ## Returns
    /// 
    /// Returns a `TransactionResult` containing the signature and tip amount.
    /// 
    /// ## Example
    /// 
    /// ```rust
    /// # async fn example(client: lightspeed_sdk::LightspeedClient) -> Result<(), Box<dyn std::error::Error>> {
    /// # use solana_sdk::{signature::Keypair, signer::Signer, system_instruction, hash::Hash};
    /// let payer = Keypair::new();
    /// let recipient = solana_sdk::pubkey::Pubkey::new_unique();
    /// 
    /// let instruction = system_instruction::transfer(
    ///     &payer.pubkey(),
    ///     &recipient,
    ///     1_000_000,
    /// );
    /// 
    /// let result = client.send_transaction(
    ///     vec![instruction],
    ///     &payer.pubkey(),
    ///     &[&payer],
    ///     Hash::default(), // Use real blockhash in production
    /// ).await?;
    /// 
    /// println!("Transaction: {}", result.signature);
    /// println!("Tip paid: {} lamports", result.tip_amount);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn send_transaction<T: Signer>(
        &self,
        instructions: Vec<Instruction>,
        payer: &Pubkey,
        signers: &[&T],
        recent_blockhash: solana_sdk::hash::Hash,
    ) -> Result<TransactionResult, LightspeedError> {
        self.send_transaction_with_priority(
            instructions,
            payer,
            signers,
            recent_blockhash,
            self.config.default_priority
        ).await
    }

    /// Sends a transaction with a specific priority level
    /// 
    /// Similar to `send_transaction` but allows overriding the default priority
    /// for this specific transaction.
    /// 
    /// ## Arguments
    /// 
    /// * `instructions` - Transaction instructions to execute
    /// * `payer` - Account paying for transaction fees and tip
    /// * `signers` - All required transaction signers
    /// * `recent_blockhash` - Recent blockhash from the cluster
    /// * `priority` - Priority level for this transaction
    /// 
    /// ## Priority Levels
    /// 
    /// - `Priority::Minimum` - 0.0001 SOL tip
    /// - `Priority::Standard` - 0.001 SOL tip
    /// - `Priority::Rush` - 0.005 SOL tip
    /// - `Priority::Custom(lamports)` - Custom tip amount
    pub async fn send_transaction_with_priority<T: Signer>(
        &self,
        mut instructions: Vec<Instruction>,
        payer: &Pubkey,
        signers: &[&T],
        recent_blockhash: solana_sdk::hash::Hash,
        priority: Priority,
    ) -> Result<TransactionResult, LightspeedError> {
        let tip_amount = priority.to_lamports();

        if tip_amount < MIN_TIP_LAMPORTS {
            return Err(LightspeedError::TipBelowMinimum(tip_amount, MIN_TIP_LAMPORTS));
        }

        // Optional balance check before sending
        if self.config.check_balance_before_send {
            // Calculate total lamports needed
            let mut transfer_total = 0u64;

            // Sum up transfer amounts from system program instructions
            for instruction in &instructions {
                if instruction.program_id == solana_sdk::system_program::id()
                    && instruction.data.len() >= 4 {
                    // Check if this is a transfer instruction (instruction type 2)
                    let instruction_type = u32::from_le_bytes([
                        instruction.data[0],
                        instruction.data[1],
                        instruction.data[2],
                        instruction.data[3],
                    ]);

                    if instruction_type == 2 && instruction.data.len() >= 12 {
                        // Extract transfer amount (8 bytes after the 4-byte instruction type)
                        let amount = u64::from_le_bytes([
                            instruction.data[4],
                            instruction.data[5],
                            instruction.data[6],
                            instruction.data[7],
                            instruction.data[8],
                            instruction.data[9],
                            instruction.data[10],
                            instruction.data[11],
                        ]);
                        transfer_total = transfer_total.saturating_add(amount);
                    }
                }
            }

            // Total needed: transfers + tip + transaction fee buffer (5000 lamports)
            let total_needed = transfer_total
                .saturating_add(tip_amount)
                .saturating_add(5000);

            if self.config.debug {
                log::debug!(
                    "Balance check: transfers={}, tip={}, fee_buffer=5000, total={}",
                    transfer_total, tip_amount, total_needed
                );
            }

            self.check_balance(payer, total_needed).await?;
        }

        // Append tip instruction
        let tip_instruction = system_instruction::transfer(
            payer,
            &self.tip_pubkey,
            tip_amount,
        );
        instructions.push(tip_instruction);

        // Build and sign transaction
        let mut transaction = Transaction::new_with_payer(
            &instructions,
            Some(payer),
        );
        transaction.sign(signers, recent_blockhash);

        // Submit to Lightspeed
        let signature = self.send_transaction_internal(&transaction).await?;

        Ok(TransactionResult {
            signature,
            tip_amount,
        })
    }

    /// Sends a transaction with a custom tip amount
    /// 
    /// Provides direct control over the tip amount in lamports.
    /// 
    /// ## Arguments
    /// 
    /// * `instructions` - Transaction instructions to execute
    /// * `payer` - Account paying for transaction fees and tip
    /// * `signers` - All required transaction signers
    /// * `recent_blockhash` - Recent blockhash from the cluster
    /// * `tip_lamports` - Tip amount in lamports
    pub async fn send_transaction_with_tip<T: Signer>(
        &self,
        instructions: Vec<Instruction>,
        payer: &Pubkey,
        signers: &[&T],
        recent_blockhash: solana_sdk::hash::Hash,
        tip_lamports: u64,
    ) -> Result<TransactionResult, LightspeedError> {
        self.send_transaction_with_priority(
            instructions,
            payer,
            signers,
            recent_blockhash,
            Priority::Custom(tip_lamports),
        ).await
    }

    /// Creates a tip instruction using the default priority
    /// 
    /// Use this when manually constructing transactions that need tip instructions.
    /// 
    /// ## Arguments
    /// 
    /// * `payer` - Account that will pay the tip
    pub fn create_tip_instruction(&self, payer: &Pubkey) -> Instruction {
        let tip_amount = self.config.default_priority.to_lamports();
        system_instruction::transfer(
            payer,
            &self.tip_pubkey,
            tip_amount,
        )
    }

    /// Creates a tip instruction with a specific priority
    /// 
    /// ## Arguments
    /// 
    /// * `payer` - Account that will pay the tip
    /// * `priority` - Priority level determining tip amount
    pub fn create_tip_instruction_with_priority(&self, payer: &Pubkey, priority: Priority) -> Instruction {
        let tip_amount = priority.to_lamports();
        system_instruction::transfer(
            payer,
            &self.tip_pubkey,
            tip_amount,
        )
    }

    /// Creates a tip instruction with a custom amount
    /// 
    /// ## Arguments
    /// 
    /// * `payer` - Account that will pay the tip
    /// * `tip_lamports` - Tip amount in lamports
    pub fn create_tip_instruction_with_tip(&self, payer: &Pubkey, tip_lamports: u64) -> Instruction {
        system_instruction::transfer(
            payer,
            &self.tip_pubkey,
            tip_lamports,
        )
    }

    /// Sends a pre-built transaction through Lightspeed
    /// 
    /// The transaction should already include a tip instruction. This method
    /// provides direct control for advanced use cases.
    /// 
    /// ## Arguments
    /// 
    /// * `transaction` - Signed transaction including tip instruction
    /// 
    /// ## Example
    /// 
    /// ```rust
    /// # async fn example(client: lightspeed_sdk::LightspeedClient) -> Result<(), Box<dyn std::error::Error>> {
    /// # use solana_sdk::{signature::Keypair, signer::Signer, transaction::Transaction, hash::Hash};
    /// let payer = Keypair::new();
    /// 
    /// // Build transaction with tip
    /// let tip = client.create_tip_instruction(&payer.pubkey());
    /// let mut tx = Transaction::new_with_payer(
    ///     &[tip],
    ///     Some(&payer.pubkey()),
    /// );
    /// tx.sign(&[&payer], Hash::default());
    /// 
    /// // Send through Lightspeed
    /// let signature = client.send_prebuilt_transaction(&tx).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn send_prebuilt_transaction(
        &self,
        transaction: &Transaction,
    ) -> Result<Signature, LightspeedError> {
        if self.config.debug {
            log::debug!("Sending transaction through Lightspeed");
        }
        self.send_transaction_internal(transaction).await
    }

    /// Updates the tip recipient address
    /// 
    /// ## Arguments
    /// 
    /// * `new_tip_address` - New tip address as a base58 string
    /// 
    /// ## Errors
    /// 
    /// Returns an error if the address is not a valid Solana public key.
    pub fn set_tip_address(&mut self, new_tip_address: &str) -> Result<(), LightspeedError> {
        let new_pubkey = Pubkey::from_str(new_tip_address)
            .map_err(|_| LightspeedError::InvalidTipAddress(
                new_tip_address.to_string()
            ))?;
        
        self.tip_pubkey = new_pubkey;
        
        if self.config.debug {
            log::debug!("Updated tip address to: {}", new_tip_address);
        }
        
        Ok(())
    }
    
    /// Returns the current tip recipient address
    pub fn get_tip_address(&self) -> Pubkey {
        self.tip_pubkey
    }

    /// Internal transaction submission handler
    async fn send_transaction_internal(
        &self,
        transaction: &Transaction,
    ) -> Result<Signature, LightspeedError> {
        // Serialize transaction
        let tx_bytes = bincode::serialize(&transaction)
            .map_err(|e| LightspeedError::TransactionFailed(e.to_string()))?;
        
        // Encode as base64
        let encoded = BASE64.encode(&tx_bytes);
        
        let request = serde_json::json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "sendTransaction",
            "params": [
                encoded,
                {
                    "skipPreflight": true,
                    "encoding": "base64"
                }
            ]
        });

        if self.config.debug {
            log::debug!("Sending transaction to endpoint: {}", self.endpoint);
        }

        let response = self.http_client
            .post(self.endpoint.clone())
            .json(&request)
            .send()
            .await?;

        let response_text = response.text().await?;
        
        if self.config.debug {
            log::debug!("Raw response: {}", response_text);
        }

        // Parse response
        let result: serde_json::Value = serde_json::from_str(&response_text)
            .map_err(|e| {
                if self.config.debug {
                    log::error!("Failed to parse response as JSON: {}", response_text);
                }
                LightspeedError::TransactionFailed(format!("Invalid JSON response: {}", e))
            })?;
        
        if let Some(error) = result.get("error") {
            return Err(LightspeedError::TransactionFailed(
                error.to_string()
            ));
        }

        let sig_str = result["result"]
            .as_str()
            .ok_or_else(|| LightspeedError::TransactionFailed("Invalid response".to_string()))?;

        Signature::from_str(sig_str)
            .map_err(|_| LightspeedError::TransactionFailed("Invalid signature".to_string()))
    }

    /// Sends a keep-alive request to maintain connection
    ///
    /// This is called automatically when keep-alive is enabled via `start_keep_alive()`.
    /// Can also be called manually if needed.
    pub async fn keep_alive(&self) -> Result<(), LightspeedError> {
        let request = serde_json::json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "getHealth"
        });

        if self.config.debug {
            log::debug!("Sending keep-alive");
        }

        self.http_client
            .post(self.endpoint.clone())
            .json(&request)
            .send()
            .await?;

        Ok(())
    }

    /// Checks if an account has sufficient balance for a transaction
    ///
    /// Verifies that the account has enough lamports to cover the transaction
    /// amount plus the tip. Includes a buffer for transaction fees (~5000 lamports).
    ///
    /// ## Arguments
    ///
    /// * `account` - The account to check
    /// * `amount_needed` - Total lamports needed (transfer amount + tip + fee buffer)
    ///
    /// ## Returns
    ///
    /// Returns `Ok(())` if balance is sufficient, otherwise returns
    /// `InsufficientBalance` error with needed and available amounts.
    async fn check_balance(&self, account: &Pubkey, amount_needed: u64) -> Result<(), LightspeedError> {
        let rpc_url = &self.config.balance_check_rpc_url;

        let request = serde_json::json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "getBalance",
            "params": [account.to_string()]
        });

        if self.config.debug {
            log::debug!("Checking balance for account: {}", account);
        }

        let response = self.http_client
            .post(rpc_url)
            .json(&request)
            .send()
            .await?;

        let result: serde_json::Value = response.json().await?;

        if let Some(error) = result.get("error") {
            return Err(LightspeedError::TransactionFailed(
                format!("RPC balance check failed: {}", error)
            ));
        }

        let balance = result["result"]["value"]
            .as_u64()
            .ok_or_else(|| LightspeedError::TransactionFailed(
                "Invalid balance response from RPC".to_string()
            ))?;

        if self.config.debug {
            log::debug!("Account balance: {} lamports, needed: {} lamports", balance, amount_needed);
        }

        if balance < amount_needed {
            return Err(LightspeedError::InsufficientBalance(amount_needed, balance));
        }

        Ok(())
    }

    /// Creates a lightweight clone for the keep-alive task
    fn clone_for_keep_alive(&self) -> Self {
        Self {
            config: self.config.clone(),
            http_client: self.http_client.clone(),
            endpoint: self.endpoint.clone(),
            tip_pubkey: self.tip_pubkey,
            keep_alive_handle: Arc::new(Mutex::new(None)),
        }
    }

    /// Stops the automatic keep-alive task
    /// 
    /// ## Returns
    /// 
    /// Returns `true` if a keep-alive task was running and has been stopped,
    /// `false` if no task was running.
    /// 
    /// ## Example
    /// 
    /// ```rust
    /// # async fn example(client: lightspeed_sdk::LightspeedClient) -> Result<(), Box<dyn std::error::Error>> {
    /// client.start_keep_alive().await?;
    /// // ... do work ...
    /// let was_running = client.stop_keep_alive().await;
    /// assert!(was_running);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn stop_keep_alive(&self) -> bool {
        let mut handle_guard = self.keep_alive_handle.lock().await;
        
        if let Some(handle) = handle_guard.take() {
            handle.abort();
            if self.config.debug {
                log::debug!("Keep-alive task stopped");
            }
            true
        } else {
            false
        }
    }
}