mev-beta/docs/DEVELOPER_DOCS.md

Development Tools & Commands Documentation

This document provides comprehensive documentation for all development tools and commands available in this project, as well as reusable tools for other projects.

Makefile Commands

Build & Run Commands

• make build - Build the application (bin/mev-beta for production)
• make run - Build and run the application
• make build-race - Build with race detection

Production Commands

• ./bin/mev-beta start - Run production binary (requires PROVIDER_CONFIG_PATH env var)
• ./scripts/log-manager.sh analyze - Production log analysis with health scoring
• ./scripts/log-manager.sh dashboard - Generate operations dashboard
• ./scripts/log-manager.sh monitor - Real-time performance monitoring
• ./scripts/archive-logs.sh - Archive and compress log files

Multi-Level Testing System

Basic Testing

• make test - Run all tests
• make test-basic - Run basic tests (fast, with -short flag)

Unit Testing

• make test-unit - Run unit tests (from ./test/unit/... and ./pkg/...)

Integration Testing

• make test-integration - Run integration tests (from ./test/integration/...)

End-to-End Testing

• make test-e2e - Run end-to-end tests (from ./test/e2e/...)

Advanced Testing

• make test-property - Run property tests (from ./test/property/...)
• make test-fuzzing - Run fuzzing tests (from ./test/fuzzing/...)
• make test-stress - Run stress tests (from ./test/stress/...)
• make test-security - Run security tests (from ./test/security/...)
• make test-bench - Run benchmark tests

Comprehensive Testing

• make test-comprehensive - Run unit + integration + e2e tests
• make test-audit - Run comprehensive + security + stress + benchmark tests

Test Coverage

• make test-coverage - Run tests with coverage report
• make test-coverage-pkg PKG=./pkg/my-package/ - Coverage for specific package

Math-Specific Testing

• make test-math - Run math tests
• make test-math-bench - Run math benchmarks
• make test-math-property - Run math property tests
• make test-math-all - Run all math tests

Code Quality & Auditing

• make fmt - Format code with go fmt
• make vet - Vet code with go vet
• make lint - Lint code with golangci-lint
• make audit-security - Run security audit with gosec and govulncheck
• make audit-deps - Run dependency audit
• make audit-quality - Run code quality audit (vet + lint)
• make audit-full - Run comprehensive audit (all checks)
• make math-audit - Run deterministic math audit

Development Workflow

• make dev-setup - Setup development environment
• make dev-deps - Install development dependencies
• make dev-workflow - Run development workflow (fmt + vet + lint + basic test)
• make dev-workflow-full - Run development workflow with coverage
• make debug - Run application in debug mode with dlv
• make watch-tests - Watch for changes and run basic tests (requires entr)
• make watch-dev - Watch for changes and run dev workflow (requires entr)

Documentation Generation

• make docs - Generate general code documentation
• make docs-api - Generate API documentation
• make docs-all - Generate all documentation

Maintenance Commands

• make clean - Clean build artifacts
• make deps - Install dependencies
• make update - Update dependencies
• make help - Show help

Simulation Commands

• make simulate-profit - Run profitability simulation

Reusable Scripts

Universal Test Runner

• Script: scripts/test-runner.sh
• Purpose: Run tests with different levels of coverage, reusable across projects
• Usage:

  # Run basic tests
  ./scripts/test-runner.sh -l basic
  
  # Run comprehensive tests with coverage
  ./scripts/test-runner.sh -l comprehensive -c
  
  # Run tests for specific packages
  ./scripts/test-runner.sh -p ./pkg/my-package/...
  

Universal Build Tool

• Script: scripts/build.sh
• Purpose: Build Go applications with configurable options, reusable across projects
• Usage:

  # Build with default settings
  ./scripts/build.sh
  
  # Build with specific name and output
  ./scripts/build.sh -n myapp -o bin/myapp
  
  # Cross-compile for different OS/arch
  ./scripts/build.sh --goos linux --goarch amd64
  

Development Setup Script

• Script: scripts/setup-dev.sh
• Purpose: Setup development environment with required tools and directories
• Usage: ./scripts/setup-dev.sh

Performance Profiling Script

• Script: scripts/performance-profile.sh
• Purpose: Profile application performance and run benchmarks
• Usage: ./scripts/performance-profile.sh

Project Template Creator

• Script: scripts/create-project-template.sh
• Purpose: Create a new Go project with standardized structure and tooling
• Usage: ./scripts/create-project-template.sh my-new-project

Global Tools Manager

• Script: scripts/mev-tools.sh
• Purpose: Install and manage global tools across multiple projects
• Usage:

  # Install tools to $HOME/bin
  ./scripts/mev-tools.sh install
  
  # Setup a new project
  ./scripts/mev-tools.sh setup-project my-project
  
  # Check environment
  ./scripts/mev-tools.sh check-env
  

Global Tools Installation

To install tools globally for use across all projects:

1. Run the installation command:

   ./scripts/mev-tools.sh install
   

2. Add $HOME/bin to your PATH (if not automatically added):

   echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

3. After installation, you can use tools like:

   test-runner -l comprehensive
   build-tool -n myapp
   

Configuration

Environment Variables

The scripts support several environment variables for customizing behavior:

• TEST_LEVEL: Level of tests to run (default: "basic")
• COVERAGE: Enable test coverage (default: "false")
• OUTPUT_DIR: Output directory for reports (default: "test-results")
• PACKAGE_FILTER: Go package filter (default: "./...")
• TIMEOUT: Test timeout duration (default: "10m")
• JUNIT_OUTPUT: Generate JUnit output (default: "false")
• BINARY_NAME: Name of the binary (default: current directory name)
• BINARY_DIR: Directory for binaries (default: "bin")
• BUILD_TAGS: Build tags for Go
• LDFLAGS: Ldflags for Go build
• PROFILE_TYPES: Profile types (default: "cpu,mem,block,mutex")
• REPORT_DIR: Directory for reports (default: "reports/performance")

Configuration File

You can export these variables in a .envrc file that can be sourced by scripts:

export TEST_LEVEL="comprehensive"
export COVERAGE="true"
export OUTPUT_DIR="reports/test-results"

Then source it before running commands:

source .envrc
make test-comprehensive

Recommended Development Workflow

1. Setup Environment:

   make dev-setup
   

2. Daily Development:

   make dev-workflow
   

3. Before Commit:

   make dev-workflow-full
   

4. Periodic Comprehensive Testing:

   make test-audit
   make audit-full
   

5. Production Deployment (Validated Oct 24, 2025):

   # Set required environment variables
   export MEV_BOT_ENCRYPTION_KEY="production_ready_encryption_key_32_chars_minimum_length_required"
   export PROVIDER_CONFIG_PATH=$PWD/config/providers_runtime.yaml
   
   # Start bot
   ./bin/mev-beta start
   
   # Monitor in separate terminal
   ./scripts/log-manager.sh analyze
   tail -f logs/mev_bot.log | grep -E "Arbitrage|PROFIT|DEX Transaction"
   

CI/CD Integration

All commands are designed to work well in CI/CD pipelines. You can use the following patterns:

• Pull Request Validation: make dev-workflow
• Nightly Builds: make test-audit
• Release Validation: make audit-full

Troubleshooting

Common Issues

1. Entr Command Not Found:

   • Install with apt-get install entr (Ubuntu/Debian) or brew install entr (macOS)
   • Required for watch-tests and watch-dev targets

2. Missing Dependencies:

   • Run make dev-deps to install all development dependencies
   • Or run make dev-setup for complete setup

3. Permission Issues:

   • Ensure scripts are executable: chmod +x scripts/*.sh
   • Make sure you have write permissions to the project directory

4. Go Version Compatibility:

   • Check go.mod for required Go version
   • Update with go mod tidy if needed