first commit

README.md

@@ -0,0 +1,75 @@
+# 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.
+