feat(utils): Add address and validation utility modules with comprehensive tests

[AdekunleBamz]

Summary

This PR adds two new utility modules to src/ethereum/utils/ that provide commonly needed helper functions for Ethereum address operations and data validation. Both modules include comprehensive unit tests.

Changes

New Files

src/ethereum/utils/address.py

Address utility functions including:

• is_valid_address_length() - Validate 20-byte address length
• is_zero_address() - Check if address is the zero address
• is_precompile_address() - Check if address is a precompile (configurable max)
• address_to_uint() - Convert address to unsigned integer
• uint_to_address() - Convert unsigned integer to address
• to_checksum_address() - Convert to EIP-55 checksummed string
• is_valid_checksum_address() - Validate EIP-55 checksum

src/ethereum/utils/validation.py

Data validation utilities including:

• is_valid_gas_limit() - Validate gas limit bounds
• is_valid_nonce() - Validate nonce per EIP-2681
• is_valid_block_number() - Validate block numbers
• is_valid_u256() / is_valid_u64() - Validate integer bounds
• is_valid_hash() / is_zero_hash() - Hash validation
• is_valid_chain_id() - Validate chain IDs per EIP-2294
• validate_transaction_value() - Validate transaction values
• is_valid_base_fee() - Validate base fee (post-London)

Test Files

• tests/common/test_address_utils.py - Comprehensive tests for address utilities
• tests/common/test_validation_utils.py - Comprehensive tests for validation utilities

Modified Files

• src/ethereum/utils/__init__.py - Updated docstring to document available modules

Motivation

These utilities consolidate common validation and address operations that are used across multiple forks. By centralizing them in the utils package:

1. Reduces code duplication across fork implementations
2. Improves consistency in validation logic
3. Provides well-documented, tested functions for contributors
4. Follows existing patterns in the codebase (similar to hexadecimal.py, numeric.py, byte.py)

Testing

All new functions include comprehensive unit tests covering:

• Valid inputs (happy path)
• Boundary conditions (min/max values)
• Invalid inputs (negative, overflow, wrong types)
• Edge cases (zero values, empty bytes)

References

• EIP-55: Mixed-case checksum address encoding
• EIP-2681: Limit account nonce to 2^64-1
• EIP-2294: Explicit bound to Chain ID

[spencer-tb]

Thanks for the contribution! The helper functions look useful but in general I don't see a reason to add them unless they are used anywhere in the specs - cc @gurukamath @Carsons-Eels - wdyt?

[gurukamath]

Thanks for the contribution! The helper functions look useful but in general I don't see a reason to add them unless they are used anywhere in the specs - cc @gurukamath @Carsons-Eels - wdyt?

@spencer-tb I agree.

[spencer-tb]

Closing for now!