feat: create precompile for native mint

[tac0turtle]

Description

The native mint precompile allows a whitelisted address to mint the native token of the chain, thus bridges being able to mint the gas token used by the evm

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Refactoring

Related Issues

Fixes #(issue)

Checklist

• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

Additional Notes

[claude]

Claude finished @tac0turtle's task —— View job

---

Code Review Complete

I've completed a thorough review of the native mint precompile implementation. This is a well-architected feature with comprehensive testing and documentation.

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review core precompile implementation
• Analyze integration points and factory changes
• Examine test coverage and quality
• Check configuration and security aspects
• Address existing reviewer concerns
• Provide comprehensive feedback summary

---

Review Summary

This PR introduces a native token minting precompile that allows whitelisted addresses to mint/burn the native gas token. The implementation is well-designed with strong security measures and comprehensive testing.

Code Quality ✅

Strengths:

• Clean, well-structured code following Rust best practices
• Comprehensive error handling with descriptive error messages
• Good separation of concerns between authorization, balance operations, and state management
• Excellent documentation including ADR-0002 with architectural rationale
• Consistent naming conventions and code organization

Minor suggestions:

• The magic bytecode [0xFE] in crates/ev-precompiles/src/mint.rs:39 could benefit from a comment explaining it represents the INVALID opcode
• Consider adding more granular tracing for debugging mint/burn operations

Security Analysis 🔐

Strong Security Design:

• Dual authorization model (admin + allowlist) provides flexibility while maintaining control
• Overflow/underflow protection on balance operations using checked_add/checked_sub
• Proper state management ensuring accounts are created and touched correctly
• Address zero filtering for mint admin prevents accidental disabling

Addressing Reviewer Concerns:

1. Admin Configuration (crates/ev-precompiles/src/mint.rs:27): The admin can indeed be a deterministic contract address using CREATE2, as suggested by @damiannolan
2. Solidity Interface (crates/ev-precompiles/src/mint.rs:14): The interface is well-defined and @damiannolan's suggestion to import from the token router is valid for production use

Security Considerations:

• Admin private key security is critical - compromise allows unlimited minting
• No rate limiting on mint operations (by design for bridge flexibility)
• Networks should implement monitoring for unusual minting patterns

Performance & Gas Usage ⚡

Good Performance Characteristics:

• Zero gas consumption by design (returns gas_used: 0)
• Minimal state reads/writes with efficient storage key derivation
• Direct EVM internals manipulation avoiding unnecessary overhead

Addressing Gas Limit Concern:
@damiannolan raised an important point about gas usage. The current implementation returns PrecompileOutput::new(0, Bytes::new()) with zero gas consumption. This is intentional design for admin operations, but consider:

• Adding configurable gas consumption for production networks
• Documenting the zero-gas design decision more clearly

Test Coverage 🧪

Excellent Test Suite:

• Unit tests: 8 comprehensive test cases covering all functionality
• Integration tests: End-to-end scenarios with full transaction flow
• Edge cases: Overflow, underflow, unauthorized access properly tested
• State verification: Balance changes, account creation, and journaling verified

Test Quality:

• Clear test names and assertions
• Good coverage of both positive and negative scenarios
• Proper setup and teardown with isolated test contexts

Architecture & Integration 🏗️

Well-Integrated Design:

• Clean factory pattern in crates/ev-revm/src/factory.rs for precompile installation
• Proper configuration management via chainspec in crates/node/src/config.rs
• Optional feature that doesn't affect networks without mint admin configured

Design Patterns:

• Singleton pattern for precompile ID and bytecode
• Lazy initialization with OnceLock for static resources
• Proper dependency injection of admin address

Specific File Analysis

crates/ev-precompiles/src/mint.rs

• Line 212/223: Zero gas usage is consistent with admin operation design
• Line 170: Allowlist key derivation is secure and collision-resistant
• Line 106-112: Authorization checks are properly structured with admin bypass

crates/ev-revm/src/factory.rs

• Line 48-61: Clean precompile installation with proper Arc sharing
• Line 228-313: Excellent integration test demonstrating proxy contract functionality

crates/node/src/config.rs

• Line 45-47: Smart handling of zero address to disable mint admin
• Line 34-50: Robust configuration parsing with proper error handling

Recommendations

1. Gas Usage: Consider adding a small gas cost for mint/burn operations to prevent potential abuse
2. Monitoring: Implement events/logs for mint/burn operations for better observability
3. Documentation: Add more inline comments for complex state management operations
4. Rate Limiting: Consider adding optional rate limiting for production deployments

Overall Assessment

This is a high-quality implementation that demonstrates:

• Strong security-first design
• Comprehensive testing and documentation
• Clean architecture with proper separation of concerns
• Thoughtful consideration of reviewer feedback

The code is production-ready with the minor suggestions noted above. The ADR provides excellent context for the design decisions, and the test coverage gives confidence in the implementation's correctness.

Recommendation: Approve with consideration of the gas usage discussion raised by @damiannolan.