chore: add guide on fee system

[tac0turtle]

Description

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

---

PR Review: Fee System Guide Documentation

Review Tasks:

• Read and analyze the new fee-systems.md documentation
• Review content for technical accuracy and clarity
• Check for consistency with existing codebase documentation
• Provide feedback on documentation structure and completeness
• Submit comprehensive review feedback

Review Feedback

✅ Strengths

1. Clear Structure: The documentation follows a logical flow from overview to individual components to integration patterns.

2. Accurate Cross-References: All referenced documentation files exist:

   • docs/adr/ADR-0001-base-fee-redirect.md
   • docs/adr/ADR-0002-native-minting-precompile.md
   • docs/contracts/fee_vault.md
   • docs/contracts/admin_proxy.md

3. Well-Explained Relationships: The guide effectively explains how the three components (base fee redirect, FeeVault, native minting) work independently and together.

4. Configuration Examples: Provides concrete JSON configuration examples for chainspec setup.

5. Security Considerations: Appropriately emphasizes the separation of concerns between fee redirection (value transfer) and native minting (supply changes).

🔍 Technical Accuracy

The documentation appears technically sound with:

• Correct precompile address format (0x000000000000000000000000000000000000f100)
• Proper EIP-1559 base fee mechanics description
• Accurate activation height concepts
• Logical security model for native minting with admin controls

📝 Suggestions for Improvement

1. Minor Formatting: Line 41 could use consistent formatting with other bullet points (ensure proper indentation).

2. Consider Adding:

   • Gas cost implications for the base fee redirect mechanism
   • Example threshold values for FeeVault operations
   • Security recommendations for mintAdmin key management

3. Deployment Considerations: The suggested deployment pattern is good, but could benefit from mentioning:

   • Testing procedures before activation
   • Monitoring recommendations post-deployment

🎯 Overall Assessment

This is high-quality documentation that effectively serves as a comprehensive guide for understanding the fee system components. It strikes the right balance between technical detail and accessibility, making it valuable for both implementers and operators.

The documentation:

• ✅ Follows established documentation patterns in the repository
• ✅ Provides accurate technical information
• ✅ Includes proper cross-references
• ✅ Maintains security focus
• ✅ Offers practical deployment guidance

Recommendation: ✅ Approve - This documentation adds significant value to the repository and maintains high quality standards.

---