Crates

Crate	Version	Docs
clmm-lp-domain
clmm-lp-simulation
clmm-lp-optimization
clmm-lp-protocols
clmm-lp-execution
clmm-lp-data
clmm-lp-cli
clmm-lp-api

CLMM Liquidity Provider Strategy Optimizer - Solana

A powerful, production-ready strategy optimization and execution engine for liquidity providers on Solana Concentrated Liquidity Market Makers (CLMMs). This project supports Orca Whirlpools, Raydium CLMM, and Meteora DLMM.

Built for market makers and sophisticated LPs who need to:

• Analyze pools and calculate impermanent loss (IL) in real-time
• Simulate positions over historical data with multiple rebalancing strategies
• Execute automated rebalancing based on volatility, volume, and asset correlation
• Monitor positions with real-time alerts and notifications
• Access everything via CLI, REST API, or Web Dashboard

🚀 Value Proposition

DeFi market making requires more than just chasing high APY. This project solves three critical problems:

1. Risk Quantification: Precise calculation of impermanent loss risks before entering positions.
2. Range Optimization: Finding the mathematical optimal tick ranges to maximize fee capture while minimizing IL.
3. Scenario Simulation: Stress-testing positions against historical and Monte Carlo simulated market conditions.

🏗 Architecture

The project follows a Domain-Driven Design (DDD) approach, separated into modular crates within a cargo workspace.

graph TD
    subgraph "User Interfaces"
        User[User]
        Browser[Web Browser]
    end
    
    User --> CLI[CLI Crate]
    User --> API[API Crate]
    Browser --> Dashboard[Web Dashboard]
    Dashboard --> API
    
    subgraph "Application Layer"
        CLI --> Optimization[Optimization Crate]
        CLI --> Simulation[Simulation Crate]
        API --> Execution[Execution Crate]
        API --> Protocols[Protocols Crate]
    end
    
    subgraph "Core Domain"
        Optimization --> Domain[Domain Crate]
        Simulation --> Domain
        Execution --> Domain
        Protocols --> Domain
    end
    
    subgraph "Infrastructure"
        Simulation --> Data[Data Crate]
        Execution --> Protocols
        Protocols --> Data
        Data --> DB[(PostgreSQL)]
    end
    
    subgraph "External Services"
        Protocols -.-> |RPC| Solana[Solana Blockchain]
        Data -.-> |HTTP| Birdeye[Birdeye API]
        Data -.-> |HTTP| Jupiter[Jupiter API]
        API -.-> |WebSocket| Clients[WS Clients]
    end

Module Overview

Web Dashboard

🛠 Tech Stack

Backend (Rust)

Frontend (TypeScript)

📅 Roadmap & Status

The project is being built in incremental phases. Current version: 0.1.1-alpha.2

Overall Progress: ~100% (Phases 0-13 complete, Phase 14 planned for future)

✨ Features

Core Capabilities

• CLMM Mathematics: Full implementation of concentrated liquidity math (tick ↔ price, sqrt_price, liquidity calculations)
• Impermanent Loss: Precise IL calculation for concentrated positions with range boundaries
• Backtesting: Simulate LP positions against historical price data with multiple rebalancing strategies
• Optimization: Find optimal tick ranges using Grid Search with configurable objective functions
• Multi-Protocol: Support for Orca Whirlpools, Raydium CLMM (Meteora DLMM planned)

Rebalancing Strategies

Optimization Objectives

• Maximize Net PnL - Total return after fees and IL
• Maximize Fee Earnings - Focus on fee capture
• Maximize Sharpe Ratio - Risk-adjusted returns
• Minimize IL - Conservative IL minimization
• Maximize Time in Range - Optimize for range efficiency

Live Monitoring

• Position Tracking: Real-time position state from on-chain
• PnL Calculation: Entry value, current value, fees, IL, net PnL, APY
• Alert System: Configurable rules for range exit, IL thresholds, PnL targets
• Multi-Channel Notifications: Console, file, webhook

REST API

• OpenAPI/Swagger: Full API documentation at /docs
• JWT Authentication: Secure API access with role-based permissions
• API Key Support: Alternative authentication method
• WebSocket: Real-time position updates and alerts

Web Dashboard

• Portfolio Overview: Total value, PnL, fees, impermanent loss
• Position Management: View, rebalance, collect fees, close positions
• Strategy Control: Create, configure, start/stop automated strategies
• Pool Explorer: Browse pools with TVL, volume, and APY metrics
• Real-time Updates: WebSocket integration for live data

⚡️ Quick Start

Prerequisites

• Rust: 1.90+ (edition 2024)
• Node.js: 18+ (for web dashboard)
• Make: Build automation
• Docker: Optional, for PostgreSQL
• PostgreSQL: 14+ (optional, for persistence)

Installation

# Clone the repository
git clone https://github.com/joaquinbejar/CLMM-Liquidity-Provider.git
cd CLMM-Liquidity-Provider

# Build the project
make build

# Run tests
make test

# Install CLI globally (optional)
cargo install --path crates/cli

Common Commands

The project includes a comprehensive Makefile for common tasks:

# Build the project
make build

# Run all tests (Unit & Integration)
make test

# Format code
make fmt

# Run Clippy lints
make lint

# Fix linting issues automatically
make lint-fix

# Pre-push checks (format + lint + test)
make pre-push

# Generate Documentation
make doc-open

Running the API Server

# Start the API server (default port 8080)
cargo run --bin clmm-lp-api

# Or with environment variables
RUST_LOG=info API_PORT=8080 cargo run --bin clmm-lp-api

The API will be available at:

• REST API: http://localhost:8080/api/v1
• Swagger UI: http://localhost:8080/docs
• WebSocket: ws://localhost:8080/ws

Running the Web Dashboard

# Navigate to web directory
cd web

# Install dependencies
npm install

# Start development server
npm run dev

The dashboard will be available at http://localhost:3000.

Note: The web dashboard requires the API server to be running on port 8080.

CLI Usage

# Analyze a trading pair
clmm-lp-cli analyze --symbol-a SOL --symbol-b USDC --days 30

# Run a backtest with periodic rebalancing
clmm-lp-cli backtest --symbol-a SOL --symbol-b USDC \
  --capital 10000 --lower-price 80 --upper-price 120 \
  --strategy periodic --rebalance-interval 24

# Optimize range parameters
clmm-lp-cli optimize --symbol-a SOL --symbol-b USDC \
  --capital 10000 --objective sharpe

# Fetch and cache market data
clmm-lp-cli data fetch --symbol SOL --days 90

# Monitor a live position
clmm-lp-cli monitor --position <POSITION_ADDRESS> --interval 30

Output Formats

The CLI supports multiple output formats:

• Table: Rich formatted tables (default)
• JSON: Machine-readable JSON output
• CSV: Spreadsheet-compatible export
• HTML: Web-ready reports
• Markdown: Documentation-friendly format

📂 Project Structure

CLMM-Liquidity-Provider/
├── Cargo.toml              # Workspace configuration
├── Makefile                # Task runner
├── .env.example            # Environment variables template
├── crates/
│   ├── api/                # REST API (Axum)
│   │   ├── handlers/       # Request handlers
│   │   ├── models.rs       # API request/response models
│   │   ├── auth.rs         # JWT & API key authentication
│   │   ├── openapi.rs      # Swagger/OpenAPI documentation
│   │   └── websocket.rs    # WebSocket handlers
│   ├── cli/                # CLI application
│   │   ├── commands/       # analyze, backtest, optimize, data, monitor
│   │   └── output/         # table, chart, export modules
│   ├── data/               # Data layer
│   │   ├── providers/      # Birdeye, Jupiter API clients
│   │   ├── repositories/   # PostgreSQL repositories
│   │   ├── cache/          # In-memory and file caching
│   │   └── migrations/     # SQL migration files
│   ├── domain/             # Core business logic
│   │   ├── entities/       # Pool, Position, Token
│   │   ├── metrics/        # IL, fees, PnL calculations
│   │   └── math/           # Tick math, liquidity, sqrt_price
│   ├── execution/          # Live execution engine
│   │   ├── alerts/         # Alert rules and notifiers
│   │   ├── monitor/        # Position monitor, PnL tracker
│   │   ├── strategy/       # Decision engine, executor
│   │   ├── transaction/    # Builder, manager
│   │   └── wallet/         # Wallet management
│   ├── optimization/       # Strategy optimization
│   │   ├── grid_search.rs  # Grid search optimizer
│   │   └── objectives.rs   # Objective functions
│   ├── protocols/          # Blockchain adapters
│   │   ├── orca/           # Whirlpool reader, executor
│   │   ├── rpc/            # RPC provider with failover
│   │   └── events/         # Event fetcher and parser
│   └── simulation/         # Backtesting engine
│       ├── models/         # Price path, volume, liquidity
│       └── strategies/     # Static, Periodic, Threshold, IL Limit
├── web/                    # Web Dashboard (React)
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── pages/          # Page components
│   │   ├── lib/            # API client, utilities
│   │   └── hooks/          # React hooks
│   ├── package.json
│   └── vite.config.ts
├── Docker/                 # Docker deployment
│   ├── docker-compose.yml  # Docker Swarm configuration
│   ├── api.Dockerfile      # API server image
│   ├── cli.Dockerfile      # CLI tool image
│   ├── web.Dockerfile      # Web dashboard image
│   ├── nginx.conf          # Nginx reverse proxy
│   └── monitoring/         # Prometheus, Grafana, AlertManager
├── tests/
│   └── load/k6/            # Load testing scripts
└── doc/                    # Documentation
    ├── steps.md            # Implementation roadmap
    ├── resume.md           # Project overview
    ├── PROGRESS.md         # Development progress tracker
    └── BACKUP_DISASTER_RECOVERY.md  # DR procedures

🧪 Testing Strategy

We employ a rigorous testing strategy to ensure financial safety:

1. Unit Tests: For all mathematical formulas (Tick Math, IL)
2. Property-Based Tests: To verify invariants (e.g., "Liquidity can never be negative")
3. Integration Tests: Mocked RPC calls to verify protocol adapters
4. Simulation Tests: Monte Carlo runs to stress-test strategies
5. End-to-End Tests: Full workflow testing with test fixtures

# Run all tests
make test

# Run with coverage
make coverage

# Run specific crate tests
cargo test -p clmm-lp-domain
cargo test -p clmm-lp-simulation

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# Solana RPC
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_RPC_BACKUP_URL=https://solana-api.projectserum.com

# Database (optional)
DATABASE_URL=postgres://user:pass@localhost:5432/clmm_lp

# API Configuration
API_HOST=0.0.0.0
API_PORT=8080
JWT_SECRET=your-secret-key-change-in-production

# Data Providers
BIRDEYE_API_KEY=your-birdeye-api-key
JUPITER_API_URL=https://price.jup.ag/v4

# Logging
RUST_LOG=info,clmm_lp=debug

Strategy Configuration

Strategies can be configured via JSON files:

{
  "name": "SOL-USDC Rebalancer",
  "strategy_type": "threshold",
  "pool_address": "HJPjoWUrhoZzkNfRpHuieeFk9WcZWjwy6PBjZ81ngndJ",
  "parameters": {
    "rebalance_threshold_pct": 5.0,
    "max_il_pct": 2.0,
    "min_rebalance_interval_hours": 4,
    "range_width_pct": 10.0
  }
}

🔒 Security Considerations

• Dry Run Mode: Always test strategies in dry-run mode before live execution
• API Keys: Never commit API keys or secrets to version control
• Wallet Security: Use hardware wallets or secure key management for production
• Rate Limiting: Built-in rate limiting for RPC and API calls
• Circuit Breaker: Automatic strategy pause on excessive losses

📊 API Endpoints

Health & Metrics

Positions

Strategies

Pools

Analytics

🐳 Docker Deployment

The project includes full Docker support for production deployment.

Quick Start with Docker Compose

# Navigate to Docker directory
cd Docker

# Copy environment template
cp .env.example .env

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

Available Services

Docker Images

Pre-built images are available on GitHub Container Registry:

# Pull images
docker pull ghcr.io/joaquinbejar/clmm-liquidity-provider/api:latest
docker pull ghcr.io/joaquinbejar/clmm-liquidity-provider/cli:latest
docker pull ghcr.io/joaquinbejar/clmm-liquidity-provider/web:latest

# Run CLI commands
docker run --rm ghcr.io/joaquinbejar/clmm-liquidity-provider/cli:latest --help

Building Images Locally

# Build all images
docker build -f Docker/api.Dockerfile -t clmm-lp-api .
docker build -f Docker/cli.Dockerfile -t clmm-lp-cli .
docker build -f Docker/web.Dockerfile -t clmm-lp-web .

Monitoring Stack

Start the monitoring infrastructure:

cd Docker/monitoring
docker-compose -f docker-compose.monitoring.yml up -d

Access dashboards:

• Grafana: http://localhost:3001 (admin/admin)
• Prometheus: http://localhost:9090
• AlertManager: http://localhost:9093

🧪 Load Testing

Load tests are implemented using k6:

# Install k6
brew install k6  # macOS

# Run smoke test
k6 run --vus 1 --duration 30s tests/load/k6/api-load-test.js

# Run full load test
k6 run tests/load/k6/api-load-test.js

# With custom API URL
k6 run -e API_BASE_URL=http://api.example.com tests/load/k6/api-load-test.js

Test scenarios include:

• Smoke: Verify system works (1 VU, 30s)
• Load: Normal load (20-50 VUs, 9m)
• Stress: Find breaking point (100-200 VUs, 16m)
• Spike: Sudden traffic spike (0-100 VUs)

🔄 CI/CD Pipeline

The project uses GitHub Actions for continuous integration and deployment:

All workflows run on every push and pull request to ensure code quality.

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and ensure tests pass: make pre-push
4. Commit with conventional commits: git commit -m 'feat: add amazing feature'
5. Push to your fork: git push origin feature/amazing-feature
6. Open a Pull Request

Development Guidelines

• Follow Rust idioms and best practices
• Add documentation for all public items
• Write tests for new functionality
• Keep PRs focused and atomic
• Use make lint-fix before committing

📞 Contact

• Author: Joaquín Béjar García
• Email: jb@taunais.com
• Telegram: @joaquin_bejar
• Repository: https://github.com/joaquinbejar/CLMM-Liquidity-Provider
• Documentation: https://docs.rs/clmm-liquidity-provider

✍️ License

This project is dual-licensed under:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

You may choose either license.

⚠️ Disclaimer

This software is provided for educational and research purposes. Trading cryptocurrencies and providing liquidity involves significant risk. The authors are not responsible for any financial losses incurred through the use of this software. Always do your own research and never invest more than you can afford to lose.