docs: add rules for cursor, kiro, windsurf

2026-07-27 23:37:45 +00:00 · 2025-08-11 05:50:45 +00:00
parent 8ab8932168
commit 7f544e93f9
9 changed files with 1614 additions and 0 deletions
@@ -0,0 +1,248 @@
+---
+trigger: always_on
+---
+
+# Trading Bot Specific Rules
+
+## Bot Configuration Standards
+
+### YAML Configuration Structure
+Maintain consistent structure across all bot configuration files:
+
+```yaml
+# Bot identification
+name: "bot-sniper-1"
+platform: "pump_fun"  # or "lets_bonk"
+enabled: true  # Allow disabling without removing config
+separate_process: true  # Run in separate process for isolation
+
+# Environment and connection
+env_file: ".env"
+rpc_endpoint: "${SOLANA_NODE_RPC_ENDPOINT}"
+wss_endpoint: "${SOLANA_NODE_WSS_ENDPOINT}"
+private_key: "${SOLANA_PRIVATE_KEY}"
+
+# Platform-specific configurations
+geyser:  # For faster data streams
+  endpoint: "${GEYSER_ENDPOINT}"
+  api_token: "${GEYSER_API_TOKEN}"
+  auth_type: "x-token"
+
+# Trading parameters
+trade:
+  buy_amount: 0.0001  # SOL amount
+  buy_slippage: 0.3   # 30%
+  sell_slippage: 0.3
+  exit_strategy: "time_based"  # "tp_sl", "manual"
+  extreme_fast_mode: true  # Skip validations for speed
+```
+
+### Environment Variable Usage
+- Use `${VARIABLE_NAME}` syntax for environment interpolation
+- Never hardcode sensitive values in YAML files
+- Validate all required environment variables on startup
+- Provide clear error messages for missing variables
+
+## Trading Logic Rules
+
+### Transaction Handling
+- Always use priority fees for competitive transaction inclusion
+- Implement retry mechanisms with exponential backoff
+- Cache recent blockhash to avoid repeated RPC calls
+- Use compute unit limits to prevent transaction failures
+
+```python
+# Good transaction building pattern
+instructions = [
+    set_compute_unit_limit(300_000),
+    set_compute_unit_price(priority_fee),
+    # ... trading instructions
+]
+```
+
+### Risk Management
+- Implement position size limits
+- Use slippage protection on all trades
+- Set maximum hold times to prevent stuck positions
+- Validate token data before trading
+
+```python
+# Risk validation example
+if token_age > self.max_token_age:
+    logger.warning(f"Token {mint} too old ({token_age}s), skipping")
+    return False
+
+if buy_amount > self.max_position_size:
+    logger.error(f"Buy amount {buy_amount} exceeds max position size")
+    return False
+```
+
+### Exit Strategies
+Implement multiple exit strategy types:
+
+1. **Time-based**: Hold for fixed duration
+2. **Take Profit/Stop Loss**: Price-based exits
+3. **Manual**: No automatic selling
+
+```python
+class ExitStrategy(Enum):
+    TIME_BASED = "time_based"
+    TP_SL = "tp_sl"
+    MANUAL = "manual"
+```
+
+## Platform Integration Rules
+
+### Multi-Platform Support
+- Use platform enum for type safety
+- Implement platform-specific address providers
+- Abstract platform differences in universal components
+- Validate platform-listener combinations
+
+```python
+# Platform validation
+if not validate_platform_listener_combination(platform, listener_type):
+    supported = get_supported_listeners_for_platform(platform)
+    raise ConfigurationError(
+        f"Listener '{listener_type}' not supported for {platform.value}. "
+        f"Supported: {supported}"
+    )
+```
+
+### Listener Types
+Support multiple data source types:
+- **geyser**: Fastest, requires special endpoint
+- **logs**: WebSocket log subscription
+- **blocks**: Block subscription (not all providers support)
+- **pumpportal**: Third-party aggregator
+
+## Performance Optimization
+
+### Speed vs Accuracy Tradeoffs
+- **Extreme Fast Mode**: Skip validations and price checks for speed
+- **Normal Mode**: Full validation and price checks
+- **Marry Mode**: Only buy, never sell (accumulation strategy)
+- **YOLO Mode**: Continuous trading without cooldowns
+
+### Caching Strategy
+```python
+# Cache expensive operations
+self._cached_blockhash: Hash | None = None
+self._blockhash_lock = asyncio.Lock()
+
+# Background blockhash updater
+async def start_blockhash_updater(self, interval: float = 5.0):
+    while True:
+        try:
+            blockhash = await self.get_latest_blockhash()
+            async with self._blockhash_lock:
+                self._cached_blockhash = blockhash
+        except Exception as e:
+            logger.exception(f"Failed to update blockhash: {e}")
+        await asyncio.sleep(interval)
+```
+
+## Monitoring and Logging
+
+### Log File Management
+- Create timestamped log files per bot instance
+- Format: `{bot_name}_{timestamp}.log`
+- Store in `logs/` directory
+- Implement log rotation for long-running bots
+
+### Trading Event Logging
+Log all significant events with context:
+
+```python
+# Good logging examples
+logger.info(f"New token detected: {mint} by {creator}")
+logger.info(f"Buy transaction submitted: {signature}")
+logger.warning(f"Transaction failed, attempt {attempt}/{max_attempts}")
+logger.error(f"Platform {platform.value} not supported")
+```
+
+### Performance Metrics
+Track key performance indicators:
+- Token detection latency
+- Transaction confirmation time
+- Success/failure rates
+- Slippage and fill rates
+
+## Security and Safety Rules
+
+### Private Key Management
+- Store private keys only in environment variables
+- Never log or expose private keys
+- Use separate wallets for testing vs production
+- Implement wallet balance checks before trading
+
+### Input Validation
+```python
+# Validate all external inputs
+def validate_mint_address(mint_str: str) -> bool:
+    try:
+        mint = Pubkey.from_string(mint_str)
+        return len(str(mint)) == 44  # Valid Solana address length
+    except Exception:
+        return False
+```
+
+### Error Recovery
+- Implement graceful shutdown on critical errors
+- Provide cleanup mechanisms for stuck positions
+- Support manual intervention modes
+- Log all errors with sufficient context for debugging
+
+## Testing and Validation
+
+### Learning Examples Usage
+Use learning examples for:
+- Testing new features before integration
+- Validating platform-specific functionality
+- Performance benchmarking
+- Educational purposes for new developers
+
+```bash
+# Test platform connectivity
+uv run learning-examples/fetch_price.py
+
+# Validate bonding curve calculations
+uv run learning-examples/compute_associated_bonding_curve.py
+
+# Compare listener performance
+uv run learning-examples/listen-new-tokens/compare_listeners.py
+```
+
+### Configuration Testing
+- Validate YAML syntax and required fields
+- Test environment variable interpolation
+- Verify platform-listener compatibility
+- Check wallet connectivity and balance
+
+## Deployment Guidelines
+
+### Production Checklist
+1. Test configuration with learning examples
+2. Verify environment variables are set
+3. Check wallet has sufficient SOL for gas fees
+4. Enable separate processes for isolation
+5. Monitor logs for successful startup
+6. Implement monitoring and alerting
+
+### Multi-Bot Management
+- Use descriptive bot names in configurations
+- Separate log files per bot instance
+- Monitor resource usage across all bots
+- Implement centralized configuration management
+
+```python
+# Bot process management
+if cfg.get("separate_process", False):
+    p = multiprocessing.Process(
+        target=run_bot_process, 
+        args=(str(file),), 
+        name=f"bot-{bot_name}"
+    )
+    p.start()
+    processes.append(p)
+```