lightspeed-sdk 0.1.0

# Lightspeed SDK for Rust

[![Crates.io](https://img.shields.io/crates/v/lightspeed-sdk.svg)](https://crates.io/crates/lightspeed-sdk)
[![Documentation](https://docs.rs/lightspeed-sdk/badge.svg)](https://docs.rs/lightspeed-sdk)
[![License](https://img.shields.io/crates/l/lightspeed-sdk.svg)](https://github.com/solana-vibe-station/lightspeed-sdk-rust#license)

Fast, reliable transaction processing for Solana using Solana Vibe Station's Lightspeed RPC service.

## Overview

Lightspeed SDK provides a simple, efficient way to submit prioritized transactions to the Solana blockchain through Solana Vibe Station's optimized RPC infrastructure. The SDK handles tip management, connection pooling, and transaction prioritization automatically.

## Features

- 🚀 **Automatic Tip Management** - Transactions automatically include appropriate priority tips
- ⚡ **Multiple Priority Levels** - Choose between Minimum, Standard, Rush, or Custom priority
- 🔄 **Connection Keep-Alive** - Maintains persistent connections for optimal performance
- 📦 **Full Solana SDK Compatibility** - Works seamlessly with existing Solana code
- 🔐 **Secure Authentication** - API key authentication via HTTP headers
- 📊 **Transaction Tracking** - Returns signatures and tip amounts for monitoring

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
lightspeed-sdk = "0.1.0"
solana-sdk = "2.1"
tokio = { version = "1", features = ["full"] }
```

## Quick Start

```rust
use lightspeed_sdk::{LightspeedClientBuilder, Priority};
use solana_sdk::{
    signature::Keypair,
    signer::Signer,
    system_instruction,
    hash::Hash,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client
    let client = LightspeedClientBuilder::new("your-api-key")
        .svs_rpc_url("https://basic.rpc.solanavibestation.com")
        .default_priority(Priority::Standard)
        .build()?;

    // Start keep-alive for connection management
    client.start_keep_alive().await?;

    // Create a transaction
    let payer = Keypair::new();
    let recipient = solana_sdk::pubkey::Pubkey::new_unique();
    
    let instruction = system_instruction::transfer(
        &payer.pubkey(),
        &recipient,
        1_000_000, // 0.001 SOL
    );

    // Send with automatic tip injection
    let result = client.send_transaction(
        vec![instruction],
        &payer.pubkey(),
        &[&payer],
        Hash::default(), // Use real blockhash in production
    ).await?;

    println!("Transaction sent: {}", result.signature);
    println!("Tip paid: {} lamports", result.tip_amount);

    Ok(())
}
```

## Usage Examples

### Different Priority Levels

```rust
use lightspeed_sdk::Priority;

// Standard priority (0.001 SOL tip)
let result = client.send_transaction(
    instructions,
    &payer.pubkey(),
    &[&payer],
    blockhash,
).await?;

// Minimum priority (0.0001 SOL tip)
let result = client.send_transaction(
    instructions,
    &payer.pubkey(),
    &[&payer],
    blockhash,
    Priority::Minimum,
).await?;


// Rush priority (0.005 SOL tip)
let result = client.send_transaction_with_priority(
    instructions,
    &payer.pubkey(),
    &[&payer],
    blockhash,
    Priority::Rush,
).await?;

// Custom tip amount (0.01 SOL)
let result = client.send_transaction_with_tip(
    instructions,
    &payer.pubkey(),
    &[&payer],
    blockhash,
    10_000_000, // lamports
).await?;
```

### Manual Tip Control

```rust
// Create tip instruction manually
let tip_instruction = client.create_tip_instruction_with_priority(
    &payer.pubkey(),
    Priority::Rush,
);

// Build transaction with tip
let mut transaction = Transaction::new_with_payer(
    &[transfer_instruction, tip_instruction],
    Some(&payer.pubkey()),
);

// Sign and send
transaction.sign(&[&payer], blockhash);
let signature = client.send_raw_transaction(&transaction).await?;
```

### Configuration Options

```rust
use std::time::Duration;

let client = LightspeedClientBuilder::new("your-api-key")
    .svs_rpc_url("https://elite.rpc.solanavibestation.com") // SVS RPC URL
    .default_priority(Priority::Rush)                       // Default priority
    .timeout(Duration::from_secs(60))                       // Request timeout
    .keep_alive_interval(Duration::from_secs(30))           // Keep-alive interval
    .debug(true)                                            // Enable debug logging
    .build()?;
```

## API Documentation

### Core Methods

| Method | Description |
|--------|-------------|
| `send_transaction()` | Send transaction with default priority |
| `send_transaction_with_priority()` | Send with specific priority |
| `send_transaction_with_tip()` | Send with custom tip amount |
| `send_raw_transaction()` | Send pre-built transaction |
| `create_tip_instruction()` | Create tip instruction |
| `start_keep_alive()` | Start connection maintenance |
| `stop_keep_alive()` | Stop connection maintenance |

### Priority Levels

| Level | Tip Amount | Use Case |
|-------|------------|----------|
| `Priority::Standard` | 0.001 SOL | Regular transactions |
| `Priority::Rush` | 0.005 SOL | Extremely time-sensitive transactions |
| `Priority::Custom(u64)` | Custom | Fine-grained control |

## Getting Started

1. **Get an SVS RPC Subscription**: Sign up for RPC services at [Solana Vibe Station](https://cloud.solanavibestation.com) to get access to Lightspeed with your RPC url and API Key

3. **Install the SDK**: Add the dependency to your Cargo.toml

4. **Start Building**: Use the examples above to integrate Lightspeed into your application

## Requirements

- Rust 1.75.0 or later
- Tokio runtime for async operations
- Valid Staked RPC/Lightspeed API key from Solana Vibe Station

## Examples

Check out the [examples](examples/) directory for more detailed usage examples:

- `basic_usage.rs` - Complete example showing all features
- More examples coming soon!

## Support

- **Documentation**: [docs.rs/lightspeed-sdk](https://docs.rs/lightspeed-sdk)
- **Issues**: [GitHub Issues](https://github.com/solana-vibe-station/lightspeed-sdk-rust/issues)
- **Discord**: Join our [Discord community](https://discord.gg/solanavibestation)
- **Email**: support@solanavibestation.com

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

Licensed under either of

 * Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license
   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

## About Solana Vibe Station

[Solana Vibe Station](https://solanavibestation.com) provides high-performance RPC infrastructure for the Solana blockchain. Our Lightspeed service offers prioritized transaction processing with guaranteed delivery and minimal latency.

---

Built with ❤️ by the Solana Vibe Station team