Description
Problem
Brittleness Signal: PathBasedWorldStateKeyValueStorage exists as abstract class with single BonsaiWorldStateKeyValueStorage implementation, creating unnecessary indirection in storage layer
Frequency: Affects 72 files across storage, sync, and API layers
Investigation Time: Developers navigate abstract/concrete type hierarchies when debugging storage issues
Root Cause
Hidden Coupling: Single implementation abstraction with complex dependencies
Files Involved: 72 files referencing either PathBasedWorldStateKeyValueStorage or BonsaiWorldStateKeyValueStorage
Key Coupling Points:
- WorldStateStorageCoordinator uses type-based routing via strategy pattern
- Controlled casting patterns in BesuControllerBuilder for component API requirements
- TrieLogPruner and BonsaiArchiver constructors require PathBasedWorldStateKeyValueStorage methods
- Plugin interface exposure through WorldStateKeyValueStorage hierarchy
- Storage format detection logic tied to concrete types
Casting Pattern Analysis:
// Type-safe strategy selection
final BonsaiWorldStateKeyValueStorage worldStateKeyValueStorage =
worldStateStorageCoordinator.getStrategy(BonsaiWorldStateKeyValueStorage.class);
// Component API requirements necessitate casting
new TrieLogPruner((BonsaiWorldStateKeyValueStorage) worldStateStorage, ...)
new BonsaiArchiver((PathBasedWorldStateKeyValueStorage) worldStateStorage, ...)Why It Exists: Originally designed for multiple storage implementations, but only Bonsai implementation materialized. The casting patterns exist due to legitimate API requirements where components need different levels of the inheritance hierarchy.
Proposed Solution
Approach: Consolidate abstract class functionality into concrete BonsaiWorldStateKeyValueStorage while preserving component API contracts
Scope: 72 files across ethereum/core, ethereum/eth, ethereum/api modules + tests
Success Criteria:
- Eliminate abstract PathBasedWorldStateKeyValueStorage class
- Preserve all storage functionality and APIs
- Maintain plugin interface compatibility
- Eliminate controlled casting patterns through API flattening
- No serialization format changes
Implementation Plan
Step 1: Component API analysis (1 day)
- Audit TrieLogPruner, BonsaiArchiver, and other component constructor requirements
- Identify which PathBasedWorldStateKeyValueStorage methods are actually needed
- Plan API consolidation to eliminate casting requirements
Step 2: Plugin interface compatibility review (1 day)
- Audit WorldStateKeyValueStorage plugin interface exposure
- Ensure consolidation doesn't break plugin API compatibility
- Document any required plugin migration steps
Step 3: Storage coordinator refactoring (1 day)
- Update WorldStateStorageCoordinator strategy pattern
- Simplify type-based routing logic with consolidated class
- Ensure storage format detection still works correctly
Step 4: Core storage consolidation and API flattening (1 day)
- Merge abstract class functionality into BonsaiWorldStateKeyValueStorage
- Update component constructors to eliminate casting requirements
- Update all type references from abstract to concrete class
- Verify DI patterns work with flattened hierarchy
Safety Checks
- Plugin interface compatibility maintained
- Component API requirements preserved without casting
- Storage format and serialization unchanged
- Type-based routing logic preserved
- All storage operations function identically
- No breaking changes to public APIs
Definition of Done
- PathBasedWorldStateKeyValueStorage abstract class removed
- All 72 files updated with consolidated implementation
- Casting patterns in BesuControllerBuilder eliminated
- Component constructors updated for flattened API
- Full test suite passes without functional changes
- Storage coordinator routing verified working
- Plugin compatibility confirmed
- No performance regressions detected
Estimated effort: 4 days
Risk level: Medium - requires careful API flattening and component integration updates
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]