🚀 Lighter RS - Rust SDK for Lighter Protocol

A production-ready Rust SDK for trading on Lighter Protocol - the lightning-fast order book DEX.

Build high-performance trading applications with the power of Rust and the speed of Lighter Protocol. Fully tested on mainnet with real transactions and comprehensive documentation to get you started in minutes.

✨ What Makes This SDK Special

🔐 Production-Grade Cryptography - Poseidon2 hashing & Schnorr signatures implemented
⚡ Blazing Fast - Rust's zero-cost abstractions for maximum performance
🛡️ Type-Safe - Catch errors at compile time, not runtime
✅ Battle-Tested - 41 unit tests passing, verified on mainnet
📚 Well-Documented - 120+ KB of guides, examples, and tutorials
🎯 Easy to Use - Get started in 5 minutes with our quick start guide

🌟 Features

Core Trading Operations ✅

📈 Market Orders - Open and close positions instantly
🎯 Limit Orders - Place orders on the book
🛑 Stop Loss - Protect your positions
💰 Take Profit - Secure your gains
✏️ Modify Orders - Update price and size
❌ Cancel Orders - Remove orders from book

Advanced Features

🔄 Position Management - Full control over your positions
⚖️ Leverage Control - Adjust leverage per market
💸 Fund Transfers - Move funds between accounts
🏊 Pool Operations - Create and manage liquidity pools
🔐 API Key Management - Secure key handling

Developer Experience

🦀 Pure Rust - No FFI, no external dependencies for core logic
⚡ Async/Await - Built on Tokio for high performance
🔍 Tracing - Structured logging with tracing-subscriber
📝 Type-Safe - Compile-time guarantees for correctness
🧪 Well-Tested - 41 unit tests, 30+ examples
🎨 Clean API - Intuitive and easy to use

📦 Installation

Add this to your Cargo.toml:

[dependencies]
lighter-rs = { git = "https://github.com/0xvasanth/lighter-rs" }
tokio = { version = "1.0", features = ["full"] }
dotenv = "0.15"

⚡ Quick Start (5 Minutes!)

Step 1: Get API Credentials

Visit app.lighter.xyz
Connect your wallet
Go to Settings → API Keys → Generate New
Save your credentials securely

Step 2: Create `.env` File

LIGHTER_API_KEY=your-40-byte-hex-key-without-0x
LIGHTER_ACCOUNT_INDEX=your-account-index
LIGHTER_API_KEY_INDEX=4
LIGHTER_CHAIN_ID=304
LIGHTER_API_URL=https://mainnet.zklighter.elliot.ai

Step 3: Write Your First Trade

use dotenv::dotenv;
use lighter_rs::client::TxClient;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing
    tracing_subscriber::fmt::init();
    dotenv().ok();

    // Create client
    let client = TxClient::new(
        &env::var("LIGHTER_API_URL")?,
        &env::var("LIGHTER_API_KEY")?,
        env::var("LIGHTER_ACCOUNT_INDEX")?.parse()?,
        env::var("LIGHTER_API_KEY_INDEX")?.parse()?,
        304, // Mainnet
    )?;

    // Open a tiny position (0.0001 ETH ≈ $0.30)
    let order = client.create_market_order(
        0,             // ETH market
        chrono::Utc::now().timestamp_millis(),
        100,           // 0.0001 ETH
        3_000_000_000, // $3000 mid price
        0,             // BUY
        false,
        None,
    ).await?;

    // Submit to Lighter
    match client.send_transaction(&order).await {
        Ok(response) if response.code == 200 => {
            tracing::info!("✅ Order placed!");
            tracing::info!("Tx Hash: {:?}", response.tx_hash);
        }
        Ok(response) => {
            tracing::warn!("Error {}: {:?}", response.code, response.message);
        }
        Err(e) => {
            tracing::error!("Failed: {}", e);
        }
    }

    Ok(())
}

Step 4: Run It!

cargo run --example create_order

You should see:

✅ Order placed!
Tx Hash: Some("abc123...")

Congratulations! 🎉 You just traded on Lighter Protocol using Rust!

📚 Documentation

New to Lighter RS? Start here:

📖 README_FOR_CUSTOMERS.md - Comprehensive user guide
🗺️ DOCUMENTATION_INDEX.md - Navigate all documentation
✅ VERIFIED_WORKING_FEATURES.md - What's tested and working

Need Help?

🔧 TROUBLESHOOTING.md - Common issues and solutions
📋 examples/ - 30+ working code examples

Want Deep Dive?

🔬 COMPREHENSIVE_IMPLEMENTATION_GUIDE.md - Technical deep dive
🧮 LIGHTER_POSEIDON2_ANALYSIS.md - Cryptography details

🎯 What Can You Build?

Trading Bots

// High-frequency trading bot
// Market making strategies
// Arbitrage systems
// Grid trading

DeFi Applications

// Automated liquidity provision
// Portfolio rebalancing
// Risk management systems

Analytics Tools

// Order flow analysis
// Market data collection
// Position tracking

The possibilities are endless! This SDK gives you the building blocks to create any trading application you can imagine.

💡 Common Use Cases

Open and Close Positions

// Open long position
let open = client.create_market_order(
    0, timestamp, 100, 3_000_000_000, 0, false, None
).await?;

// Close position (important: use reduce_only=true!)
let close = client.create_market_order(
    0, timestamp, 100, 3_000_000_000, 1, true, None
).await?;

Set Stop Loss Protection

use lighter_rs::types::CreateOrderTxReq;
use lighter_rs::constants::*;

let stop_loss = CreateOrderTxReq {
    market_index: 0,
    client_order_index: chrono::Utc::now().timestamp_millis(),
    base_amount: 100,
    price: 2_900_000_000,          // Execution price
    is_ask: 1,                     // SELL
    order_type: ORDER_TYPE_STOP_LOSS,
    time_in_force: TIME_IN_FORCE_IMMEDIATE_OR_CANCEL,  // Required for stop loss
    reduce_only: 1,
    trigger_price: 2_950_000_000,  // Trigger at $2950
    order_expiry: future_timestamp,
};

let tx = client.create_order(&stop_loss, None).await?;
client.send_transaction(&tx).await?;

Place and Cancel Limit Orders

// Place limit order
let limit = client.create_limit_order(
    market_index, timestamp, amount, price, is_ask, false, None
).await?;

client.send_transaction(&limit).await?;

// Cancel it later
let cancel = CancelOrderTxReq {
    market_index: 0,
    index: order_client_order_index,
};

let cancel_tx = client.cancel_order(&cancel, None).await?;
client.send_transaction(&cancel_tx).await?;

🛠️ Development

Running Tests

# Run all unit tests (41 tests)
cargo test

# Run specific example
cargo run --example create_order

# Run with logging
RUST_LOG=debug cargo run --example create_order

Building

# Development build
cargo build

# Optimized release build
cargo build --release

# Generate documentation
cargo doc --open

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Run all checks
cargo test && cargo clippy && cargo fmt --check

🤝 Contributing

We welcome contributions from everyone! Whether you're fixing a bug, adding a feature, or improving documentation, your help makes this project better.

How to Contribute

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-feature)
✨ Make your changes
✅ Run tests (cargo test)
📝 Commit your changes (git commit -m 'Add amazing feature')
🚀 Push to branch (git push origin feature/amazing-feature)
🎉 Open a Pull Request

Contribution Ideas

Good First Issues:

📝 Improve documentation
🐛 Fix typos or formatting
🧪 Add more test cases
📋 Create new examples
🌐 Add support for more markets

Advanced Contributions:

🔐 Enhance cryptographic implementations
⚡ Performance optimizations
🎨 API improvements
🧮 Additional transaction types
📊 Analytics features

Every contribution matters! Even small improvements help make this SDK better for everyone.

🌟 Community

Join our growing community of Rust developers building on Lighter Protocol!

Discord: Join our channel
GitHub Discussions: Share ideas and ask questions
Twitter: Follow @LighterProtocol

🏆 Project Status

✅ Core Trading: Fully functional on mainnet
✅ Cryptography: Complete Poseidon2 + Schnorr implementation
✅ Tests: 41 unit tests, all passing
✅ Documentation: 120+ KB comprehensive guides
✅ Examples: 30+ working examples
✅ Mainnet Verified: 11+ successful transactions

Status: Production-ready for market order trading! 🎉

🔐 Security

Private Key Safety:

Never commit private keys to version control
Use environment variables (.env file)
The .env file is in .gitignore by default
Regenerate keys if accidentally exposed

Audit Status: This SDK uses goldilocks-crypto and poseidon-hash crates for cryptography. While these are ports from the official lighter-go implementation, they have not been independently audited. Use appropriate caution in production.

📖 Learn More

About Lighter Protocol:

Website: lighter.xyz
Documentation: docs.lighter.xyz
API Docs: apidocs.lighter.xyz
Trade Now: app.lighter.xyz

Other SDKs:

💝 Acknowledgments

Built with ❤️ by the Rust community for the Lighter Protocol ecosystem.

Special thanks to:

The Lighter Protocol team for building an amazing DEX
Contributors to goldilocks-crypto and poseidon-hash crates
Everyone who has tested, reported issues, or contributed code

📄 License

MIT License - See LICENSE for details.

Ready to build the future of decentralized trading? 🚀

Start with our Quick Start Guide above, explore the examples, and join our community!

Happy Trading! 📈

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.env.example		.env.example
.gitignore		.gitignore
Cargo.toml		Cargo.toml
README.md		README.md

0xvasanth/lighter-rs

Folders and files

Latest commit

History

Repository files navigation