docs: add CLAUDE.md

2026-07-27 15:27:44 +00:00 · 2025-07-14 19:56:46 +00:00
parent 4c3089b70f
commit 51eae4f5a3
1 changed files with 129 additions and 0 deletions
@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Environment Setup
+```bash
+# Create virtual environment and install dependencies
+uv sync
+
+# Activate virtual environment
+source .venv/bin/activate  # Unix/macOS
+.venv\Scripts\activate     # Windows
+
+# Install bot as editable package
+uv pip install -e .
+```
+
+### Running the Bot
+```bash
+# Run bot with all configurations in bots/ directory
+pump_bot
+
+# Run bot directly
+python -m src.bot_runner
+
+# Run specific bot configuration
+python -m src.bot_runner path/to/bot-config.yaml
+```
+
+### Development Tools
+```bash
+# Lint code with ruff
+ruff check .
+
+# Format code with ruff
+ruff format .
+
+# Run both linting and formatting
+ruff check . && ruff format .
+```
+
+### Testing
+```bash
+# Run individual test files
+python tests/test_block_listener.py
+python tests/test_geyser_listener.py
+python tests/test_logs_listener.py
+```
+
+## Architecture Overview
+
+This is a Solana-based trading bot for pump.fun tokens with a modular architecture:
+
+### Core Components
+
+- **`src/bot_runner.py`**: Main entry point that loads configurations and starts trading bots
+- **`src/config_loader.py`**: Handles YAML configuration loading, validation, and environment variable resolution
+- **`src/trading/trader.py`**: `PumpTrader` class - main trading coordinator that orchestrates token detection, buying, and selling
+- **`src/core/client.py`**: `SolanaClient` - abstraction for Solana RPC operations with background blockhash caching
+- **`src/core/wallet.py`**: Wallet management for signing transactions
+- **`src/core/curve.py`**: Bonding curve calculations for pump.fun tokens
+
+### Trading System
+
+- **`src/trading/buyer.py`**: `TokenBuyer` - handles token purchase logic with slippage and retry support
+- **`src/trading/seller.py`**: `TokenSeller` - handles token sale logic 
+- **`src/trading/position.py`**: `Position` - tracks positions with take-profit/stop-loss functionality
+- **`src/trading/base.py`**: Common trading data structures (`TokenInfo`, `TradeResult`)
+
+### Token Detection (Monitoring)
+
+Multiple listener implementations for detecting new tokens:
+- **`src/monitoring/logs_listener.py`**: Uses `logsSubscribe` WebSocket method
+- **`src/monitoring/block_listener.py`**: Uses `blockSubscribe` WebSocket method  
+- **`src/monitoring/geyser_listener.py`**: Uses Geyser gRPC streaming (fastest)
+- **`src/monitoring/pumpportal_listener.py`**: Uses PumpPortal WebSocket API
+- **`src/monitoring/base_listener.py`**: Abstract base class for all listeners
+
+### Priority Fees
+
+- **`src/core/priority_fee/manager.py`**: Manages priority fee calculation
+- **`src/core/priority_fee/dynamic_fee.py`**: Dynamic fee calculation based on network conditions
+- **`src/core/priority_fee/fixed_fee.py`**: Fixed fee implementation
+
+### Configuration System
+
+Bot configurations are stored in `bots/*.yaml` files. Each bot can run independently with its own settings for:
+- Connection endpoints (RPC, WSS, Geyser)
+- Trading parameters (buy amount, slippage, exit strategy)
+- Priority fees (dynamic vs fixed)
+- Token filters (match string, creator address)
+- Cleanup modes for token accounts
+
+### Key Features
+
+1. **Multiple Listener Types**: Supports logs, blocks, Geyser, and PumpPortal for token detection
+2. **Exit Strategies**: Time-based, take-profit/stop-loss, or manual
+3. **Extreme Fast Mode**: Skips stabilization wait and price checks for faster execution
+4. **Priority Fee Management**: Dynamic or fixed fee calculation
+5. **Account Cleanup**: Automatic cleanup of empty token accounts
+6. **Multi-bot Support**: Run multiple bots with different configurations simultaneously
+
+### Trading Modes
+
+- **Single Token Mode** (`yolo_mode: false`): Process one token and exit
+- **Continuous Mode** (`yolo_mode: true`): Continuously process tokens
+- **Marry Mode** (`marry_mode: true`): Only buy tokens, skip selling
+
+## Environment Configuration
+
+Create `.env` file with:
+```
+SOLANA_NODE_RPC_ENDPOINT=your_rpc_endpoint
+SOLANA_NODE_WSS_ENDPOINT=your_wss_endpoint
+SOLANA_PRIVATE_KEY=your_private_key
+GEYSER_ENDPOINT=your_geyser_endpoint
+GEYSER_API_TOKEN=your_geyser_token
+```
+
+## Important Notes
+
+- This is educational/learning code - not for production use
+- The bot trades on pump.fun bonding curves and handles migrations to Raydium/PumpSwap
+- Geyser listener provides fastest token detection
+- All configurations support environment variable substitution with `${VAR}` syntax
+- Bot logs are stored in `logs/` directory with timestamps
+- Trade logs are written to `trades/trades.log`