# Meteora DLMM Automated Trading Bot

A high-performance TypeScript trading bot designed for Meteora's Dynamic Liquidity Market Maker (DLMM) on Solana. The bot optimizes yield through precision rebalancing, native SOL management, and resilient transaction handling.

## 🚀 Key Features

- **Precision Rebalancing (15% Rule)**: Instead of fixed intervals, the bot rebalances when the active price bin enters the outer 15% of your position's range. This ensures your liquidity stays centered and productive.
- **Micro-Frequency Monitoring**: Checks your portfolio every 5 minutes (`*/5 * * * *`) to react quickly to market volatility.
- **Native SOL Awareness**: Seamlessly handles SOL-only accounts. It detects SOL in your wallet, reserves a **0.1 SOL gas buffer**, and automatically performs initial deposits.
- **Balanced Entry (50/50 Swap)**: If you enter with only SOL, the bot uses Jupiter to automatically swap ~50% for the opposite asset, ensuring your position is productive in both directions from the start.
- **Dust Retention (ATA optimization)**: Leaves a tiny amount of tokens (0.0001) in your wallet to keep the Associated Token Accounts open, preventing repetitive SOL rent fees.
- **Value-Based Compounding**: Monitors your wallet and triggers a re-deposit whenever uninvested fees/balance exceed **$1.00 USD**.
- **Transaction Resilience**: Built-in retry logic (2 retries per operation) and exponential backoff to handle Solana network congestion.
- **Dockerized Environment**: Runs on Node 20 within a controlled Docker container to eliminate "it works on my machine" issues.

## 🛠 Prerequisites

- **Docker** (Highly Recommended)
- A Solana wallet with SOL (the bot will handle the rest).
- A reliable Solana RPC URL (Mainnet).

## 📦 Quick Start

1. **Clone & Configure**:
   ```bash
   git clone <repository-url>
   cd meteora-dlmm-bot
   cp .env.example .env
   ```
   Edit `.env` with your `RPC_URL`, `PRIVATE_KEY` (Base58), and `PAIR_ADDRESS`.

2. **Run with Docker**:
   ```bash
   make docker-build
   make docker-run
   ```

## 🧠 How It Works (Internal Logic)

### 1. The 5-Minute Cycle
Every 5 minutes, the bot wakes up and recalculates your entire portfolio state:
- Fetches the current `Active Bin` from the DLMM pool.
- Retrieves all your open positions for that specific pair.
- Queries wallet balances for both tokens (including Native SOL).

### 2. Rebalance Trigger
For each position, the bot calculates a "Healthy Range":
- If the `Active Bin` is within the middle 70% of your range, it does nothing.
- If the `Active Bin` hits the bottom 15% or top 15% "Danger Zones", a rebalance is triggered.

### 3. The Rebalance Process
When triggered, the bot:
1. **Withdraws** all liquidity from the current position.
2. **Claims** all accrued fees.
3. **Consolidates** the tokens in your wallet.
4. **Redeposits** a new position exactly centered around the new `Active Bin`, providing immediate "Spot" liquidity.

### 4. Resilience Features
- **Retries**: If a transaction fails (e.g., blockhash expired), it retries up to 2 times automatically.
- **Safety Buffer**: Always leaves 0.1 SOL in your wallet to ensure you can always pay for future rebalances and withdrawals.
- **Cycle-Level Safety**: If the RPC fails or the API is down, the bot logs the error but keeps running, attempting the check again in 5 minutes.

## 💡 Configuration Tips

- `DRY_RUN=true`: Use this to see what the bot *would* do without spending any SOL.
- `CHECK_INTERVAL_CRON`: Adjust frequency (e.g., `*/1 * * * *` for 1-minute checks).
- `REBALANCE_THRESHOLD_PERCENT`: Default is `0.15` (15%). Decrease for tighter ranges, increase for more "passive" management.

## 📜 Project Structure

- `src/bot.ts`: Core strategy logic and decision engine.
- `src/meteora.ts`: Low-level Meteora SDK interactions and retry logic.
- `src/utils/config.ts`: Environment validation and sanitization.
- `tests/`: Comprehensive test suite for rebalancing math and balance detection.