Feat/evm error stack

[cds-amal]

Implement error-stack for Enhanced Error Handling in EVM Addon

Summary

This PR introduces error-stack (v0.5.0) to the EVM addon as a proof of concept for improving error handling across the txtx project. The implementation provides rich error context while maintaining full backward compatibility with the existing Diagnostic system.

Problem Statement

The current error handling in the EVM addon has several issues:

• 196 instances of diagnosed_error! with limited context
• 71 functions returning Result<_, String> with opaque errors
• 236 instances of .map_err(|e| string conversions
• Difficult debugging due to lack of error context and stack traces

Solution

Implemented a centralized error handling system using error-stack that provides:

• Hierarchical error types with rich context
• Automatic stack trace collection (debug mode only)
• Zero-cost abstractions in release builds
• Seamless conversion to Diagnostic for compatibility

Architecture

graph TD
    A[error-stack Report] -->|At API Boundary| B[Diagnostic Conversion]
    B --> C[LSP Integration]
    B --> D[CLI Output]
    B --> E[Web UI]
    
    F[New Code] -->|Uses| A
    G[Legacy Code] -->|Uses| H[diagnosed_error!]
    H --> B
    
    style A fill:#90EE90
    style F fill:#90EE90
    style H fill:#FFE4B5
    style G fill:#FFE4B5

Loading

Error Flow Example

sequenceDiagram
    participant User
    participant EVM Module
    participant RPC
    participant Error Stack
    participant Diagnostic
    
    User->>EVM Module: Send Transaction
    EVM Module->>RPC: eth_getBalance
    RPC-->>Error Stack: Connection Failed
    Error Stack->>Error Stack: Attach RPC Context
    Error Stack->>Error Stack: Change to Transaction Error
    Error Stack->>Error Stack: Attach Transaction Context
    Error Stack->>Diagnostic: Convert at API Boundary
    Diagnostic-->>User: Rich Error Message

Loading

Migration Strategy

graph LR
    A[Phase 1<br/>Proof of Concept] -->|This PR| B[Phase 2<br/>Core Modules]
    B --> C[Phase 3<br/>All Addons]
    C --> D[Phase 4<br/>Full Adoption]
    
    A1[EVM addon<br/>error-stack] -.->|Evaluate| B
    B1[Transaction<br/>RPC<br/>Signers] -.-> C
    C1[Bitcoin<br/>Stacks<br/>Solana] -.-> D
    
    style A fill:#90EE90
    style A1 fill:#90EE90

Loading

Key Changes

1. New Error Module (src/errors.rs)

• Hierarchical error types: Transaction, RPC, Contract, Verification, Codec, Signer, Config
• Context attachments: TransactionContext, RpcContext, ContractContext
• Conversion layer: Report<EvmError> → Diagnostic

2. Demonstration Tests (src/errors_demo.rs)

Run with: cargo test errors_demo::demo_tests -- --nocapture

Shows:

• Rich error chains with full context
• Backward compatibility with Diagnostic
• Side-by-side comparison of old vs new errors

3. Example Refactored Module (src/codec/transaction_builder_refactored.rs)

Demonstrates how to refactor existing code to use error-stack

Example Error Output

Before (String Error)

Error: failed to send transaction: insufficient funds

After (error-stack)

Transaction error: Insufficient funds: required 1 ETH, available 0.5 ETH
├╴Transaction requires 1 ETH but wallet only has 0.5 ETH
├╴Transaction: Send 1 ETH from 0x7474...7474 to 0x5f5f...5f5f
├╴Suggested action: Add more funds or reduce transaction amount
│
╰─▶ RPC error: RPC node error: insufficient funds for gas * price + value
    ├╴Balance check returned: 0.5 ETH
    ╰╴RPC Endpoint: https://mainnet.infura.io

Benefits

For Developers

• 🔍 Better Debugging: Full error context with stack traces
• 🏗️ Type Safety: Strongly typed errors instead of strings
• 📊 Rich Context: Automatic attachment of relevant information
• ⚡ Performance: Zero overhead in release builds

For Users

• 💡 Actionable Errors: Suggestions for fixing issues
• 📝 Clear Messages: Hierarchical error explanations
• 🔗 Full Context: Understanding of what went wrong and why

Backward Compatibility

The implementation ensures full compatibility:

// New internal implementation
fn process() -> EvmResult<Value> {
    Err(Report::new(EvmError::Transaction(...)))
}

// At API boundary - automatic conversion
pub fn public_api() -> Result<Value, Diagnostic> {
    process().map_err(|e| report_to_diagnostic(e))
}

Testing

# Run demonstration tests
cd addons/evm
cargo test errors_demo::demo_tests -- --nocapture

# Run specific demos
cargo test demo_error_stack_to_diagnostic_conversion -- --nocapture
cargo test demo_mixed_error_handling -- --nocapture

Files Changed

• addons/evm/Cargo.toml - Added error-stack dependency
• addons/evm/src/errors.rs - Core error types and conversion
• addons/evm/src/errors_demo.rs - Demonstration tests
• addons/evm/src/codec/transaction_builder_refactored.rs - Example refactoring
• addons/evm/ERROR_STACK_MIGRATION.md - Migration guide
• addons/evm/DEMO_ERROR_STACK.md - Demo documentation

Metrics for Success

After this PR, we can evaluate:

• Error Quality: Are errors more helpful for debugging?
• Developer Experience: Is the new system easier to use?
• Performance Impact: Any regression in release builds?
• Integration Complexity: How difficult is migration?

Next Steps

Based on the success of this proof of concept:

1. If Successful: Roll out to remaining EVM modules, then other addons
2. If Adjustments Needed: Refine approach based on feedback
3. If Not Viable: Revert and explore alternatives

Review Checklist

• Error types cover all EVM error scenarios
• Conversion to Diagnostic preserves necessary information
• Demo tests clearly show benefits
• Migration guide is comprehensive
• No breaking changes to public APIs
• Performance characteristics understood

How to Review

1. Run the demo tests to see error output
2. Review the error type hierarchy in src/errors.rs
3. Check the conversion implementation for compatibility
4. Evaluate the migration guide for completeness
5. Consider if this approach would work for your module