feat: Add production-ready compute unit benchmarking framework with statistical analysis

[levicook]

Dual Benchmarking Paradigms

🔬 Instruction Benchmarking - Pure CU measurement

// Measures exactly what you ask for - no hidden overhead
let result = benchmark_instruction(sol_transfer_bench, 100);
// Result: 150 CU (0% variance) - perfectly consistent

🔄 Transaction Benchmarking - Complete workflow analysis

// Real-world multi-program scenarios
let result = benchmark_transaction(token_setup_bench, 100);
// Result: 28,322-38,822 CU range - realistic variance

Statistical Analysis Engine

Percentile-Based Estimates (inspired by Helius Priority Fee API):

{
  "cu_estimate": {
    "min": 28322,           // 0th percentile - absolute minimum
    "conservative": 30145,  // 25th percentile - safe for most cases
    "balanced": 32891,      // 50th percentile - good default  
    "safe": 35123,         // 75th percentile - high reliability
    "very_high": 37456,    // 95th percentile - very reliable
    "unsafe_max": 38822,   // 100th percentile - maximum observed
    "sample_size": 100
  }
}

🔧 Major Technical Achievements

1. Context Discovery System

• Two-phase measurement: Simulation for context + execution for statistics
• Rich execution context: SVM state, program details, CPI analysis
• Address book system: Human-readable program names vs raw pubkeys

2. Statistical Rigor

• Fixed percentile calculation bugs that were showing incorrect variance
• Comprehensive unit tests (7 test cases covering edge cases)
• Proper handling of duplicates, unsorted input, boundary conditions

3. Clean Architecture

• Modular design: Separate concerns across focused modules
• Type-safe domain modeling: StatType enum for instruction vs transaction distinction
• Professional tooling: env_logger integration, clean JSON serialization

4. Framework Design Excellence

• No hidden overhead: Removed automatic ComputeBudgetInstruction for transparency
• SVM state accumulation: Realistic measurements vs isolated tests
• User control: Benchmark authors control SVM configuration completely

📊 Working Examples & Living Documentation

Benchmarks as Primary Documentation

• SOL Transfer: cu_bench_sol_transfer_ix.rs - 150 CU pure system program call
• SPL Token Transfer: cu_bench_spl_transfer_ix.rs - Complex multi-account instruction
• Token Setup Workflow: cu_bench_token_setup_tx.rs - 5-instruction, 4-program workflow

Comprehensive Documentation

• 📖 Complete Guide: BENCHMARKING.md - 274 lines of practical documentation
• 🎯 Enhanced README: Repositions project as testing + benchmarking platform
• 💡 Learning Path: README → BENCHMARKING.md → working benchmark files

🚀 Key Design Decisions & Evolution

Problems Solved During Development

1. Multiple SVM Issue: Fixed benchmark runner creating different SVM instances
2. Account Collision Errors: Generate fresh keypairs to avoid conflicts
3. Insufficient Funds: Increased funding for long measurement runs
4. Framework Overhead: Removed hidden ComputeBudgetInstruction for transparency
5. Percentile Calculation Bug: Fixed incorrect indexing showing false consistency
6. Domain Modeling: Created proper instruction vs transaction distinction

Architecture Choices

• Living Documentation: Benchmark files serve as guaranteed-working examples
• Statistical Approach: Multiple samples → confidence intervals vs single measurements
• User Control: Framework measures exactly what users ask for, nothing more
• Professional UX: Quiet by default, rich logging via RUST_LOG=info

📈 Impact & Results

Ecosystem Positioning

Elevates litesvm-testing from "another testing framework" to unique dual-purpose toolkit:

• Testing: Comprehensive error assertions and log verification
• Benchmarking: Systematic CU analysis with statistical confidence

Concrete Value Delivered

Capability	Before	After
CU Measurement	Manual, ad-hoc	Systematic, statistical
Fee Estimation	Guesswork	Data-driven with confidence intervals
Instruction Analysis	None	Pure measurement without overhead
Transaction Analysis	None	Multi-program workflow insights
Reproducibility	Inconsistent	Professional methodology

Technical Metrics

• +1,665 lines, -506 lines across 15 files
• 324 lines of comprehensive unit tests
• 274 lines of documentation
• 3 working benchmarks demonstrating different paradigms

🔄 Migration & Integration

Existing Users: Zero breaking changes - all existing testing functionality preserved

New Capabilities: Opt-in via --features cu_bench for benchmarking functionality

Production Integration:

// Load benchmark results for fee estimation
let cu_estimate = load_benchmark_result("sol_transfer")?.cu_estimate.conservative;
let compute_budget_ix = ComputeBudgetInstruction::set_compute_unit_limit(cu_estimate);

This PR establishes litesvm-testing as the definitive toolkit for Solana program development - combining comprehensive testing utilities with production-ready performance analysis capabilities not available elsewhere in the ecosystem.

Ready for review! 🎯