mev-beta/.qwen/QWEN.md

# Qwen Code CLI Configuration

This directory contains Qwen Code configuration and tools for the MEV Bot project.

## 🚀 Quick Start Commands

### Essential Build & Test Commands
```bash
# Build the MEV bot binary
make build

# Run mathematical function tests
.qwen/scripts/math-test.sh

# Run mathematical optimization analysis
.qwen/scripts/math-optimize.sh

# Run benchmarks for mathematical functions
make bench-math

# Run property-based tests
make test-property

# Check for Go modules issues
go mod tidy && go mod verify

# Run linter on mathematical functions
golangci-lint run ./pkg/uniswap/... ./pkg/math/...
```

### Development Workflow Commands
```bash
# Setup development environment
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export METRICS_ENABLED="false"

# Run with timeout for testing
timeout 30 ./mev-bot start

# Debug with verbose logging
LOG_LEVEL=debug ./mev-bot start

# Profile performance
go tool pprof http://localhost:6060/debug/pprof/profile
```

## Qwen Commands Directory

The `.qwen/commands/` directory contains predefined commands for mathematical development tasks:

- `implement-algorithm.md` - Implement mathematical algorithms with precision
- `optimize-math.md` - Optimize mathematical performance
- `verify-precision.md` - Verify mathematical precision and correctness

## Qwen Settings

The `.qwen/settings.json` file contains Qwen's mathematical computation configuration:

```json
{
  "focus_areas": [
    "Mathematical Computations",
    "Algorithmic Implementation",
    "Precision Handling",
    "Performance Optimization"
  ],
  "primary_skills": [
    "Implementing precise Uniswap V3 pricing functions",
    "Ensuring numerical stability and precision",
    "Working with liquidity and fee calculations",
    "Creating efficient algorithms for arbitrage detection",
    "Implementing accurate tick and sqrtPriceX96 conversions",
    "Calculating price impact with proper precision handling"
  ],
  "performance_optimization": {
    "enabled": true,
    "profiling": {
      "cpu": true,
      "memory": true,
      "goroutine": true
    },
    "optimization_targets": [
      "Minimize memory allocations in hot paths",
      "Optimize uint256 arithmetic operations",
      "Reduce garbage collection pressure",
      "Improve mathematical computation efficiency",
      "Cache expensive constant calculations for repeated operations",
      "Implement lookup tables for frequently used values"
    ]
  },
  "precision_requirements": {
    "math_library": "github.com/holiman/uint256",
    "floating_point": "math/big",
    "rounding_strategy": "bankers_rounding",
    "precision_target": "256_bits"
  },
  "testing": {
    "unit_test_coverage": 95,
    "property_based_testing": true,
    "fuzz_testing": true,
    "benchmarking": true
  }
}
```

## 📋 Development Guidelines & Code Style

### Mathematical Implementation Guidelines
- **Precision**: Always use `github.com/holiman/uint256` for uint256 arithmetic
- **Error Handling**: Implement robust error handling with clear mathematical context
- **Documentation**: Document all mathematical formulas and implementation decisions
- **Testing**: Achieve >95% test coverage with property-based tests for mathematical functions
- **Performance**: Profile regularly with `go tool pprof` while maintaining precision

### Code Organization Rules
- **File Size**: Keep mathematical function files under 300 lines
- **Package Structure**: Place mathematical functions in `pkg/uniswap/` or `pkg/math/`
- **Naming**: Use descriptive names for mathematical functions (e.g., `CalculateSqrtPriceX96ToPrice`)
- **Documentation**: Inline comments explaining mathematical formulas

### Required Checks Before Commit
```bash
# Run mathematical function tests
.qwen/scripts/math-test.sh

# Run linter on mathematical functions
golangci-lint run ./pkg/uniswap/... ./pkg/math/...

# Security scan for mathematical implementations
gosec ./pkg/uniswap/... ./pkg/math/...
```

## Qwen Code's Primary Focus Areas

As Qwen Code, you're particularly skilled at:

1. **Mathematical Computations**
   - Implementing precise Uniswap V3 pricing functions
   - Ensuring numerical stability and precision
   - Working with liquidity and fee calculations

2. **Algorithmic Implementation**
   - Creating efficient algorithms for arbitrage detection
   - Implementing accurate tick and sqrtPriceX96 conversions
   - Calculating price impact with proper precision handling

3. **Precision Handling**
   - Using appropriate data types for mathematical calculations
   - Implementing proper rounding strategies for financial calculations
   - Handling overflow and underflow conditions properly

4. **Performance Optimization**
   - Minimizing memory allocations in hot paths
   - Optimizing uint256 arithmetic operations
   - Reducing garbage collection pressure
   - Improving mathematical computation efficiency
   - Caching expensive constant calculations (see [Mathematical Optimizations](docs/MATH_OPTIMIZATIONS.md))
   - Implementing lookup tables for frequently used values

## 🛠 Qwen Code Optimization Settings

### Workflow Preferences
- **Always commit changes**: Use `git commit -am "math: descriptive message"` for mathematical implementations
- **Branch naming**: Use prefixes (`math-sqrt-price`, `algo-liquidity-calc`, `perf-uniswap`)
- **Context management**: Focus on mathematical precision and performance
- **Parallel processing**: Leverage Go's concurrency patterns for independent calculations

### File Organization Preferences
- **Mathematical functions**: Place in `pkg/uniswap/` or `pkg/math/`
- **Test files**: Place alongside source files with `_test.go` suffix
- **Documentation**: Inline comments explaining mathematical formulas
- **Precision libraries**: Use `github.com/holiman/uint256` for uint256 arithmetic

### Performance Monitoring
```bash
# Enable metrics endpoint for performance tracking
export METRICS_ENABLED="true"
export METRICS_PORT="9090"

# Monitor memory usage of mathematical calculations
go tool pprof http://localhost:9090/debug/pprof/heap

# Monitor CPU usage of mathematical functions
go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30

# Run benchmarks for mathematical functions
.qwen/scripts/math-test.sh

# View detailed performance analysis
.qwen/scripts/math-optimize.sh
```

## 🔧 Environment Configuration

### Required Environment Variables
```bash
# Arbitrum RPC Configuration
export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"
export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/f69d14406bc00700da9b936504e1a870"

# Application Configuration
export LOG_LEVEL="info"
export METRICS_ENABLED="false"
export METRICS_PORT="9090"

# Development Configuration
export GO_ENV="development"
export DEBUG="true"

# Mathematical Precision Configuration
export MATH_LIBRARY="github.com/holiman/uint256"
export FLOATING_POINT_LIBRARY="math/big"
export ROUNDING_STRATEGY="bankers_rounding"
export PRECISION_TARGET="256_bits"
```

### Testing Environment Variables
```bash
# Test Configuration
export TEST_COVERAGE_TARGET=95
export TEST_TIMEOUT=30s
export TEST_PARALLEL=4

# Mathematical Testing
export MATH_TEST_PROPERTY=true
export MATH_TEST_FUZZ=true
export MATH_BENCHMARK=true
```

## 📝 Commit Message Conventions

### Format
```
math(type): brief description

- Detailed explanation of mathematical implementation
- Why the mathematical approach was chosen
- Any precision considerations or trade-offs

🤖 Generated with [Qwen Code](https://tongyi.aliyun.com/)
Co-Authored-By: Qwen <noreply@tongyi.aliyun.com>
```

### Types
- `sqrt-price`: sqrtPriceX96 related implementations
- `tick`: Tick calculation implementations
- `liquidity`: Liquidity-based calculation implementations
- `price-impact`: Price impact calculation implementations
- `arbitrage`: Arbitrage detection algorithm implementations
- `perf`: Mathematical performance improvements
- `test`: Mathematical function test implementations
- `docs`: Mathematical documentation updates

## 🚨 Security Guidelines

### Never Commit
- Private keys or wallet seeds
- API keys or secrets
- RPC endpoints with authentication
- Personal configuration files

### Always Validate
- Mathematical inputs for overflow conditions
- Precision requirements for financial calculations
- Edge cases in mathematical implementations
- Memory allocations in mathematical functions

### Security Commands
```bash
# Scan for secrets
git-secrets --scan

# Security audit for mathematical implementations
gosec ./pkg/uniswap/... ./pkg/math/...

# Dependency vulnerabilities
go list -json -m all | nancy sleuth

# Check for hardcoded credentials
grep -r "password|secret|key" --exclude-dir=.git .
```