lighter-rs 0.1.1

# 🚀 Lighter RS - Rust SDK for Lighter Protocol

[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-41%20passing-brightgreen.svg)]()

> 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`:

```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

1. Visit [app.lighter.xyz](https://app.lighter.xyz)
2. Connect your wallet
3. Go to **Settings** → **API Keys** → **Generate New**
4. Save your credentials securely

### Step 2: Create `.env` File

```bash
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

```rust
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!

```bash
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](README_FOR_CUSTOMERS.md)** - Comprehensive user guide
- 🗺️ **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** - Navigate all documentation
- ✅ **[VERIFIED_WORKING_FEATURES.md](VERIFIED_WORKING_FEATURES.md)** - What's tested and working

**Need Help?**
- 🔧 **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
- 📋 **[examples/](examples/)** - 30+ working code examples

**Want Deep Dive?**
- 🔬 **[COMPREHENSIVE_IMPLEMENTATION_GUIDE.md](COMPREHENSIVE_IMPLEMENTATION_GUIDE.md)** - Technical deep dive
- 🧮 **[LIGHTER_POSEIDON2_ANALYSIS.md](LIGHTER_POSEIDON2_ANALYSIS.md)** - Cryptography details

## 🎯 What Can You Build?

### Trading Bots
```rust
// High-frequency trading bot
// Market making strategies
// Arbitrage systems
// Grid trading
```

### DeFi Applications
```rust
// Automated liquidity provision
// Portfolio rebalancing
// Risk management systems
```

### Analytics Tools
```rust
// 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

```rust
// 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

```rust
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

```rust
// 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

```bash
# 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

```bash
# Development build
cargo build

# Optimized release build
cargo build --release

# Generate documentation
cargo doc --open
```

### Code Quality

```bash
# 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

1. **🍴 Fork the repository**
2. **🌿 Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **✨ Make your changes**
4. **✅ Run tests** (`cargo test`)
5. **📝 Commit your changes** (`git commit -m 'Add amazing feature'`)
6. **🚀 Push to branch** (`git push origin feature/amazing-feature`)
7. **🎉 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](https://discord.gg/lighter)
- **GitHub Discussions:** Share ideas and ask questions
- **Twitter:** Follow [@LighterProtocol](https://twitter.com/lighter)

## 🏆 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](https://lighter.xyz)
- Documentation: [docs.lighter.xyz](https://docs.lighter.xyz)
- API Docs: [apidocs.lighter.xyz](https://apidocs.lighter.xyz)
- Trade Now: [app.lighter.xyz](https://app.lighter.xyz)

**Other SDKs:**
- Python: [elliottech/lighter-python](https://github.com/elliottech/lighter-python)
- Go: [elliottech/lighter-go](https://github.com/elliottech/lighter-go)
- TypeScript: [hkirat/lighter-sdk-ts](https://github.com/hkirat/lighter-sdk-ts)

## 💝 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](LICENSE) for details.

---

**Ready to build the future of decentralized trading?** 🚀

Start with our [Quick Start Guide](#-quick-start-5-minutes) above, explore the [examples](examples/), and join our [community](#-community)!

**Happy Trading!** 📈