From 38cce575f58a10b9f5087e7eedb3b4127db6b52f Mon Sep 17 00:00:00 2001 From: Krypto Kajun Date: Sun, 14 Sep 2025 07:41:04 -0500 Subject: [PATCH] feat: Enhanced Claude Code configuration with comprehensive best practices MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated project CLAUDE.md with detailed commands, workflows, and guidelines - Added environment configuration and performance monitoring commands - Enhanced security guidelines and commit message conventions - Created 5 custom slash commands for common MEV bot development tasks: * /analyze-performance - Comprehensive performance analysis * /debug-issue - Structured debugging workflow * /implement-feature - Feature implementation framework * /security-audit - Security audit checklist * /optimize-performance - Performance optimization strategy - Updated global CLAUDE.md with universal best practices - Improved file organization and development standards 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/commands/analyze-performance.md | 34 ++++ .claude/commands/debug-issue.md | 43 +++++ .claude/commands/implement-feature.md | 38 +++++ .claude/commands/optimize-performance.md | 84 ++++++++++ .claude/commands/security-audit.md | 72 ++++++++ CLAUDE.md | 199 ++++++++++++++++++++++- 6 files changed, 461 insertions(+), 9 deletions(-) create mode 100644 .claude/commands/analyze-performance.md create mode 100644 .claude/commands/debug-issue.md create mode 100644 .claude/commands/implement-feature.md create mode 100644 .claude/commands/optimize-performance.md create mode 100644 .claude/commands/security-audit.md diff --git a/.claude/commands/analyze-performance.md b/.claude/commands/analyze-performance.md new file mode 100644 index 0000000..76b086b --- /dev/null +++ b/.claude/commands/analyze-performance.md @@ -0,0 +1,34 @@ +# Analyze Performance Issues + +Perform a comprehensive performance analysis of the MEV bot: $ARGUMENTS + +## Analysis Steps: +1. **Memory Profiling**: Check for memory leaks and high allocation patterns +2. **CPU Profiling**: Identify CPU bottlenecks and hot paths +3. **Goroutine Analysis**: Look for goroutine leaks and blocking operations +4. **I/O Performance**: Analyze network and disk I/O patterns +5. **Concurrency Issues**: Check for race conditions and lock contention + +## Performance Commands to Run: +```bash +# Memory profile +go tool pprof http://localhost:9090/debug/pprof/heap + +# CPU profile +go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30 + +# Goroutine analysis +go tool pprof http://localhost:9090/debug/pprof/goroutine + +# Enable race detector +go run -race ./cmd/mev-bot +``` + +## Analysis Focus Areas: +- Worker pool efficiency in `pkg/market/pipeline.go` +- Event parsing performance in `pkg/events/` +- Uniswap math calculations in `pkg/uniswap/` +- Memory usage in large transaction processing +- Rate limiting effectiveness in `internal/ratelimit/` + +Please provide specific performance metrics and recommendations for optimization. \ No newline at end of file diff --git a/.claude/commands/debug-issue.md b/.claude/commands/debug-issue.md new file mode 100644 index 0000000..97c6452 --- /dev/null +++ b/.claude/commands/debug-issue.md @@ -0,0 +1,43 @@ +# Debug MEV Bot Issue + +Debug the following MEV bot issue: $ARGUMENTS + +## Debugging Protocol: +1. **Issue Understanding**: Analyze the problem description and expected vs actual behavior +2. **Log Analysis**: Examine relevant log files in `logs/` directory +3. **Code Investigation**: Review related source code and recent changes +4. **Reproduction**: Attempt to reproduce the issue in a controlled environment +5. **Root Cause**: Identify the underlying cause and contributing factors + +## Debugging Commands: +```bash +# Check logs +tail -f logs/mev-bot.log + +# Run with debug logging +LOG_LEVEL=debug ./mev-bot start + +# Check system resources +htop +iostat -x 1 5 + +# Network connectivity +nc -zv arbitrum-mainnet.core.chainstack.com 443 + +# Go runtime stats +curl http://localhost:9090/debug/vars | jq +``` + +## Investigation Areas: +- **Connection Issues**: RPC endpoint connectivity and WebSocket stability +- **Parsing Errors**: Transaction and event parsing failures +- **Performance**: High CPU/memory usage or processing delays +- **Concurrency**: Race conditions or deadlocks +- **Configuration**: Environment variables and configuration issues + +## Output Requirements: +- Clear problem identification +- Step-by-step reproduction instructions +- Root cause analysis +- Proposed solution with implementation steps +- Test plan to verify the fix \ No newline at end of file diff --git a/.claude/commands/implement-feature.md b/.claude/commands/implement-feature.md new file mode 100644 index 0000000..0faa7dd --- /dev/null +++ b/.claude/commands/implement-feature.md @@ -0,0 +1,38 @@ +# Implement MEV Bot Feature + +Implement the following feature for the MEV bot: $ARGUMENTS + +## Implementation Framework: +1. **Requirements Analysis**: Break down the feature requirements and acceptance criteria +2. **Architecture Design**: Design the solution following existing patterns +3. **Interface Design**: Define clean interfaces between components +4. **Implementation**: Write the code following Go best practices +5. **Testing**: Create comprehensive unit and integration tests +6. **Documentation**: Update relevant documentation and examples + +## Implementation Standards: +- **Code Quality**: Follow Go conventions and project coding standards +- **Error Handling**: Implement robust error handling with context +- **Logging**: Add appropriate logging with structured fields +- **Testing**: Achieve >90% test coverage +- **Performance**: Consider performance implications and add metrics +- **Security**: Validate all inputs and handle edge cases + +## File Organization: +- **Core Logic**: Place in appropriate `pkg/` subdirectory +- **Configuration**: Add to `internal/config/` if needed +- **Tests**: Co-locate with source files (`*_test.go`) +- **Documentation**: Update `docs/` and inline comments + +## Integration Points: +- **Event System**: Integrate with `pkg/events/` for transaction processing +- **Market Pipeline**: Connect to `pkg/market/pipeline.go` for processing +- **Monitoring**: Add metrics and health checks +- **Configuration**: Add necessary environment variables + +## Deliverables: +- Working implementation with tests +- Updated documentation +- Configuration updates +- Performance benchmarks if applicable +- Migration guide for existing deployments \ No newline at end of file diff --git a/.claude/commands/optimize-performance.md b/.claude/commands/optimize-performance.md new file mode 100644 index 0000000..6dedefe --- /dev/null +++ b/.claude/commands/optimize-performance.md @@ -0,0 +1,84 @@ +# Optimize MEV Bot Performance + +Optimize the performance of the MEV bot in the following area: $ARGUMENTS + +## Performance Optimization Strategy: + +### 1. **Profiling and Measurement** +```bash +# CPU profiling +go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30 + +# Memory profiling +go tool pprof http://localhost:9090/debug/pprof/heap + +# Trace analysis +go tool trace trace.out + +# Benchmark testing +go test -bench=. -benchmem ./... +``` + +### 2. **Optimization Areas** + +#### **Concurrency Optimization** +- Worker pool sizing and configuration +- Channel buffer optimization +- Goroutine pooling and reuse +- Lock contention reduction +- Context cancellation patterns + +#### **Memory Optimization** +- Object pooling for frequent allocations +- Buffer reuse patterns +- Garbage collection tuning +- Memory leak prevention +- Slice and map pre-allocation + +#### **I/O Optimization** +- Connection pooling for RPC calls +- Request batching and pipelining +- Caching frequently accessed data +- Asynchronous processing patterns +- Rate limiting optimization + +#### **Algorithm Optimization** +- Uniswap math calculation efficiency +- Event parsing performance +- Data structure selection +- Caching strategies +- Indexing improvements + +### 3. **MEV Bot Specific Optimizations** + +#### **Transaction Processing Pipeline** +- Parallel transaction processing +- Event filtering optimization +- Batch processing strategies +- Pipeline stage optimization + +#### **Market Analysis** +- Price calculation caching +- Pool data caching +- Historical data indexing +- Real-time processing optimization + +#### **Arbitrage Detection** +- Opportunity scanning efficiency +- Profit calculation optimization +- Market impact analysis speed +- Cross-DEX comparison performance + +## Implementation Guidelines: +- Measure before optimizing (baseline metrics) +- Focus on bottlenecks identified through profiling +- Maintain code readability and maintainability +- Add performance tests for regressions +- Document performance characteristics + +## Deliverables: +- Performance benchmark results (before/after) +- Optimized code with maintained functionality +- Performance monitoring enhancements +- Optimization documentation +- Regression test suite \ No newline at end of file diff --git a/.claude/commands/security-audit.md b/.claude/commands/security-audit.md new file mode 100644 index 0000000..29b1c90 --- /dev/null +++ b/.claude/commands/security-audit.md @@ -0,0 +1,72 @@ +# MEV Bot Security Audit + +Perform a comprehensive security audit of the MEV bot focusing on: $ARGUMENTS + +## Security Audit Checklist: + +### 1. **Code Security Analysis** +```bash +# Static security analysis +gosec ./... + +# Dependency vulnerabilities +go list -json -m all | nancy sleuth + +# Secret scanning +git-secrets --scan +``` + +### 2. **Input Validation Review** +- Transaction data parsing validation +- RPC response validation +- Configuration parameter validation +- Mathematical overflow/underflow checks +- Buffer overflow prevention + +### 3. **Cryptographic Security** +- Private key handling and storage +- Signature verification processes +- Random number generation +- Hash function usage +- Encryption at rest and in transit + +### 4. **Network Security** +- RPC endpoint authentication +- TLS/SSL configuration +- Rate limiting implementation +- DDoS protection mechanisms +- WebSocket connection security + +### 5. **Runtime Security** +- Memory safety in Go code +- Goroutine safety and race conditions +- Resource exhaustion protection +- Error information disclosure +- Logging security (no sensitive data) + +## Specific MEV Bot Security Areas: + +### **Transaction Processing** +- Validate all transaction inputs +- Prevent transaction replay attacks +- Secure handling of swap calculations +- Protection against malicious contract calls + +### **Market Data Integrity** +- Price feed validation +- Oracle manipulation detection +- Historical data integrity +- Real-time data verification + +### **Financial Security** +- Gas estimation accuracy +- Slippage protection +- Minimum profit validation +- MEV protection mechanisms + +## Output Requirements: +- Detailed security findings report +- Risk assessment (Critical/High/Medium/Low) +- Remediation recommendations +- Implementation timeline for fixes +- Security testing procedures \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 6330b3f..65743b6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,49 @@ -# MEV Bot Project - Claude Context +# MEV Bot Project - Claude Code Configuration -This file contains context information for Claude about the MEV Bot project. +This file contains comprehensive Claude Code configuration and context information for the MEV Bot project. + +## 🚀 Quick Start Commands + +### Essential Build & Test Commands +```bash +# Build the MEV bot binary +make build + +# Run tests +make test + +# Start development server with hot reload +./scripts/run.sh + +# Build and run with logging +./scripts/build.sh && ./mev-bot start + +# Check for Go modules issues +go mod tidy && go mod verify + +# Run linter +golangci-lint run + +# Run security analysis +gosec ./... +``` + +### Development Workflow Commands +```bash +# Setup development environment +export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a" +export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a" +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 +``` ## Project Overview This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors the Arbitrum sequencer for potential swap opportunities. When a potential swap is detected, the bot scans the market to determine if the swap is large enough to move the price using off-chain methods. @@ -30,12 +73,34 @@ This is an MEV (Maximal Extractable Value) bot written in Go 1.24+ that monitors - Use the universal message bus for inter-module communication - Adhere to the standards defined in the project plan -## Development Guidelines -- Focus on implementing the features outlined in the project plan -- Ensure all code follows Go best practices -- Write comprehensive tests for all functionality -- Document all public APIs and complex algorithms -- Follow the performance requirements outlined in COMMON.md +## 📋 Development Guidelines & Code Style + +### Go Best Practices +- **Error Handling**: Always wrap errors with context using `fmt.Errorf("operation failed: %w", err)` +- **Concurrency**: Use worker pools for processing large datasets (see `pkg/market/pipeline.go`) +- **Interfaces**: Keep interfaces small and focused (1-3 methods maximum) +- **Testing**: Aim for >90% test coverage with table-driven tests +- **Logging**: Use structured logging with `slog` package +- **Performance**: Profile regularly with `go tool pprof` + +### Code Organization Rules +- **File Size**: Keep files under 500 lines (split larger files into logical components) +- **Package Structure**: Follow Go standard layout (cmd/, internal/, pkg/) +- **Naming**: Use Go naming conventions (PascalCase for exports, camelCase for private) +- **Documentation**: Document all exported functions with examples +- **Constants**: Group related constants in blocks with `iota` when appropriate + +### Required Checks Before Commit +```bash +# Run all checks before committing +make test && make lint && go mod tidy + +# Security scan +gosec ./... + +# Dependency vulnerability check +go list -json -m all | nancy sleuth +``` ## System Architecture The MEV Bot follows a modular architecture with clearly defined components that communicate through well-defined interfaces. @@ -112,4 +177,120 @@ As Claude, you're particularly skilled at: - Designing for horizontal scalability - Ensuring code follows established patterns and conventions -When working on this project, please focus on these areas where your strengths will be most beneficial. \ No newline at end of file +When working on this project, please focus on these areas where your strengths will be most beneficial. + +## 🛠 Claude Code Optimization Settings + +### Workflow Preferences +- **Always commit changes**: Use `git commit -am "descriptive message"` after significant changes +- **Branch naming**: Use hyphens (`feat-add-new-parser`, `fix-memory-leak`) +- **Context management**: Use `/compact` to manage long conversations +- **Parallel processing**: Leverage Go's concurrency patterns extensively + +### File Organization Preferences +- **Never save temporary files to root**: Use `/tmp/` or `internal/temp/` +- **Log files**: Always save to `logs/` directory +- **Test files**: Place alongside source files with `_test.go` suffix +- **Documentation**: Keep in `docs/` with clear naming + +### Performance Monitoring +```bash +# Enable metrics endpoint +export METRICS_ENABLED="true" +export METRICS_PORT="9090" + +# Monitor memory usage +go tool pprof http://localhost:9090/debug/pprof/heap + +# Monitor CPU usage +go tool pprof http://localhost:9090/debug/pprof/profile?seconds=30 + +# Monitor goroutines +go tool pprof http://localhost:9090/debug/pprof/goroutine +``` + +## 🔧 Environment Configuration + +### Required Environment Variables +```bash +# Arbitrum RPC Configuration +export ARBITRUM_RPC_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a" +export ARBITRUM_WS_ENDPOINT="wss://arbitrum-mainnet.core.chainstack.com/73bc682fe9c5bd23b42ef40f752fa89a" + +# Application Configuration +export LOG_LEVEL="info" +export METRICS_ENABLED="false" +export METRICS_PORT="9090" + +# Development Configuration +export GO_ENV="development" +export DEBUG="true" +``` + +### Optional Environment Variables +```bash +# Performance Tuning +export GOMAXPROCS=4 +export GOGC=100 + +# Logging Configuration +export LOG_FORMAT="json" +export LOG_OUTPUT="logs/mev-bot.log" + +# Rate Limiting +export MAX_RPS=100 +export RATE_LIMIT_BURST=200 +``` + +## 📝 Commit Message Conventions + +### Format +``` +type(scope): brief description + +- Detailed explanation of changes +- Why the change was needed +- Any breaking changes or migration notes + +🤖 Generated with [Claude Code](https://claude.ai/code) +Co-Authored-By: Claude +``` + +### Types +- `feat`: New feature implementation +- `fix`: Bug fix +- `perf`: Performance improvement +- `refactor`: Code restructuring without feature changes +- `test`: Adding or updating tests +- `docs`: Documentation updates +- `build`: Build system or dependency changes +- `ci`: CI/CD pipeline changes + +## 🚨 Security Guidelines + +### Never Commit +- Private keys or wallet seeds +- API keys or secrets +- RPC endpoints with authentication +- Personal configuration files + +### Always Validate +- Input parameters for all functions +- RPC responses before processing +- Mathematical calculations for overflow +- Memory allocations for bounds + +### Security Commands +```bash +# Scan for secrets +git-secrets --scan + +# Security audit +gosec ./... + +# Dependency vulnerabilities +go list -json -m all | nancy sleuth + +# Check for hardcoded credentials +grep -r "password\|secret\|key" --exclude-dir=.git . +``` \ No newline at end of file