feat: add ev-deployer CLI for genesis contract allocation

[randygrok]

Implements Part 1 (Core) of EV Deployer — a CLI tool for generating genesis alloc entries for ev-reth contracts via declarative TOML configuration.

The tool reads a TOML config file, encodes contract bytecode and storage state, and generates Ethereum-compatible genesis alloc JSON. Supports merging into existing genesis files with collision detection. Currently handles AdminProxy and FeeVault contracts.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fbdca447-9c3c-43a3-a478-87a0da98422b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ev-deployer-part1-core

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can customize the tone of the review comments and chat replies.

Configure the tone_instructions setting to customize the tone of the review comments and chat replies. For example, you can set the tone to Act like a strict teacher, Act like a pirate and more.

[claude]

Claude finished @randygrok's task —— View job

---

PR Review Complete ✅

I've conducted a comprehensive review of this PR implementing the EV Deployer CLI tool. Here's my detailed analysis:

Review Checklist:

• Analyze main entry point and CLI structure
• Review configuration handling and TOML parsing
• Examine contract implementations (AdminProxy, FeeVault)
• Check genesis file generation and merging logic
• Assess error handling and security considerations
• Evaluate performance implications
• Review test coverage and suggest improvements
• Check documentation quality
• Provide final recommendations

---

Overall Assessment

This is a well-architected and thoughtfully implemented CLI tool. The code demonstrates good Rust practices, solid error handling, and comprehensive testing. The functionality is cleanly separated into logical modules with appropriate abstraction layers.

Code Quality & Best Practices ✅

Strengths:

• Clean Architecture: Well-organized module structure with clear separation of concerns
• Type Safety: Excellent use of Rust's type system with proper serialization/deserialization
• Error Handling: Consistent use of eyre::Result throughout with meaningful error messages
• Memory Safety: Appropriate use of BTreeMap for deterministic ordering and safe memory management
• Code Style: Consistent formatting and idiomatic Rust patterns

Minor Improvements:

• Consider adding #[non_exhaustive] to public structs that might be extended in the future
• The hardcoded bytecode constants could benefit from build-time verification (already addressed with ignored tests)

Security Assessment ✅

Strong Security Practices:

• Input Validation: Robust validation in config.rs:83-104 preventing zero addresses and invalid basis points
• Path Safety: Safe file operations using standard library functions
• Deserialization Safety: Uses serde with appropriate error handling, no unsafe code
• Address Collision Detection: genesis.rs:46-48 properly detects and prevents accidental overwrites

No Security Concerns Identified:

• No unsafe code blocks
• No potential for buffer overflows or memory corruption
• Proper handling of user input with validation
• Safe file I/O operations

Performance Considerations ✅

Efficient Design:

• Memory Usage: Minimal allocations, appropriate data structures
• File Operations: Efficient reading/writing with proper error handling
• JSON Processing: Uses serde_json efficiently for serialization
• Storage Operations: BTreeMap provides O(log n) operations with deterministic ordering

Performance is Appropriate:

• This is a CLI tool for genesis generation (not hot path code)
• File I/O is the primary bottleneck, which is unavoidable
• Memory usage scales linearly with config size (expected behavior)

Test Coverage Assessment 📊

Excellent Test Coverage (15 tests total):

config.rs (4 tests):

• ✅ Full config parsing (parse_full_config)
• ✅ Zero address validation (reject_zero_owner)
• ✅ Basis points validation (reject_bps_over_10000)
• ✅ Partial config support (admin_proxy_only)

genesis.rs (5 tests):

• ✅ JSON structure validation (alloc_json_structure)
• ✅ Golden value verification (alloc_golden_value)
• ✅ Slot key formatting (slot_key_formatting)
• ✅ Collision detection (merge_detects_collision)
• ✅ Force overwrite (merge_force_overwrites)

Contract modules (6 tests):

• ✅ AdminProxy storage encoding (golden_admin_proxy_storage)
• ✅ FeeVault storage encoding with multiple scenarios
• ✅ Bytecode verification tests (ignored, requires forge)

Test Quality:

• Golden Tests: Verify exact expected outputs
• Edge Cases: Cover validation failures and boundary conditions
• Integration: Test full workflows including file operations

Potential Issues & Suggestions 🔍

Minor Issues:

1. Bytecode Verification Tests (admin_proxy.rs:48, fee_vault.rs:151):

   • Currently ignored and require forge CLI
   • Suggestion: Consider running these in CI (already implemented in .github/workflows/ev_deployer.yml)

2. Error Message Consistency:

   • Most error messages are clear, but could standardize format
   • Example: config.rs:87 could use consistent "AdminProxy:" prefix

3. Default Handling:

   • bridge_share_bps 0→10000 mapping is handled correctly but could be documented more clearly in config validation

Enhancement Opportunities:

1. Validation Enhancement:

   // Consider adding in config.rs validation
   eyre::ensure!(
       !ap.address.is_zero(),
       "admin_proxy.address must not be the zero address"
   );

2. CLI UX Improvements:

   • Consider adding --dry-run flag for preview mode
   • Add verbose logging option for troubleshooting

Documentation Quality ✅

Excellent Documentation:

• README: Comprehensive with clear examples and usage instructions
• Code Comments: Appropriate level of documentation without over-commenting
• Examples: devnet.toml provides clear configuration example
• CLI Help: Well-structured help text with clear descriptions

CI/CD Integration ✅

Solid CI Setup:

• Separate Jobs: Bytecode verification and unit tests run independently
• Dependency Management: Proper Foundry installation for bytecode verification
• Test Isolation: Bytecode tests run single-threaded to avoid race conditions

Final Recommendations

Ready to Merge ✅

This PR demonstrates high-quality Rust development with:

• Solid architecture and clean code
• Comprehensive test coverage (15 tests across all modules)
• Strong security practices
• Excellent documentation
• Proper CI integration

Optional Future Enhancements:

1. Add integration tests for full CLI workflows
2. Consider adding configuration schema validation
3. Add metrics/logging for production usage
4. Consider adding configuration file templating

The implementation is production-ready and follows Rust best practices. No blocking issues identified.

---