docs: add comprehensive documentation for RedBlackTreeWithResize feature

- Update README with RedBlackTreeWithResizeKV usage examples and documentation
- Add enhanced operations section showing resize functionality
- Document storage capacity management and pre-allocation benefits
- Expand test coverage section for all resize-related test suites
- Add specific use cases and guidance for when to use resize features
- Fix contract name in RedBlackTreeWithResize.sol test file
- Add storage slot cleanup logic in RedBlackTreeWithResizeLib resize function

Author: xiaozzz

README.md

@@ -14,6 +14,7 @@ The Red-Black Tree implementation is based on [Solady's RedBlackTreeLib](https:/
 - **Complex Value Support**: Stores `ValueLib.Value` structs containing any size of data. In this example, it shows 6 slots.
 - **Red-Black Tree Properties**: Maintains balanced tree structure ensuring O(log n) operations
 - **Zero Value Protection**: Prevents insertion of zero keys to maintain tree integrity
+- **Dynamic Resizing**: Pre-allocate storage capacity to optimize gas costs for future insertions (available in `RedBlackTreeWithResizeLib`)
 
 ### Gas Performance
 
@@ -38,15 +39,19 @@ The Red-Black Tree implementation shows **90% gas reduction** for hot insertions
 
 ```
 src/
-├── RedBlackTreeKV.sol      # Main KV store implementation
-├── MappingKV.sol          # Traditional mapping implementation for comparison
+├── RedBlackTreeKV.sol             # Main KV store implementation
+├── RedBlackTreeWithResizeKV.sol   # Enhanced KV store with resize capabilities
+├── MappingKV.sol                  # Traditional mapping implementation for comparison
 └── lib/
-    ├── RedBlackTreeLib.sol # Red-Black Tree data structure library
-    └── Value.sol          # Value struct definition
+    ├── RedBlackTreeLib.sol            # Red-Black Tree data structure library
+    ├── RedBlackTreeWithResizeLib.sol  # Enhanced Red-Black Tree with resize capabilities
+    └── Value.sol                      # Value struct definition
 
 test/
-├── RedBlackTreeKV.t.sol     # Comprehensive unit tests
-└── RedBlackTreeKVGas.t.sol  # Gas benchmark tests
+├── RedBlackTreeKV.t.sol           # Comprehensive unit tests
+├── RedBlackTreeWithResizeKV.t.sol # Tests for resize-enabled KV store
+├── RedBlackTreeWithResize.sol     # Red-Black Tree library tests with resize functionality
+└── RedBlackTreeKVGas.t.sol        # Gas benchmark tests
 ```
 
 ## Value Structure
@@ -95,6 +100,54 @@ kv.deleteValue(1);
 uint256[] memory keys = kv.values();
 ```
 
+### Enhanced Operations with Resize
+
+```solidity
+RedBlackTreeWithResizeKV kvWithResize = new RedBlackTreeWithResizeKV();
+
+// Pre-allocate storage for 1000 elements to optimize gas costs
+kvWithResize.resize(1000);
+
+// Check current storage metrics
+uint256 capacity = kvWithResize.getStorageSize();  // Returns 1000
+uint256 size = kvWithResize.getSize();             // Returns current number of elements
+
+// Set values with optimized gas costs
+kvWithResize.setValue(1, value);
+kvWithResize.setValue(2, anotherValue);
+
+// All other operations work the same
+ValueLib.Value memory retrieved = kvWithResize.getValue(1);
+kvWithResize.deleteValue(1);
+uint256[] memory keys = kvWithResize.values();
+```
+
+### WithResize Feature
+
+The `RedBlackTreeWithResizeLib` provides enhanced functionality for pre-allocating storage capacity to optimize gas costs:
+
+```solidity
+import "./lib/RedBlackTreeWithResizeLib.sol";
+
+RedBlackTreeWithResizeLib.Tree tree;
+
+// Pre-allocate storage for 1000 elements to save gas on future insertions
+RedBlackTreeWithResizeLib.resize(tree, 1000);
+
+// Check current storage capacity
+uint256 capacity = RedBlackTreeWithResizeLib.storageSize(tree);
+
+// Insert values with optimized gas costs
+RedBlackTreeWithResizeLib.insert(tree, 42);
+```
+
+#### Resize Benefits
+
+- **Pre-allocation**: Reserve storage slots in advance to avoid costly allocations during insertion
+- **Gas Optimization**: Significantly reduces gas costs for insertions when capacity is pre-allocated
+- **Flexible Sizing**: Dynamically adjust storage capacity based on expected usage patterns
+- **Auto-increment**: Storage capacity automatically increases when inserting beyond current capacity
+
 ### Constraints
 
 - **No Zero Keys**: Keys cannot be 0 (will revert with `ValueIsEmpty()`)
@@ -117,6 +170,11 @@ forge test
 
 # Run unit tests only
 forge test --match-contract RedBlackTreeKVTest
+forge test --match-contract RedBlackTreeWithResizeKVTest
+
+# Run resize library tests
+forge test --match-contract RedBlackTreeLibTest
+forge test --match-contract RedBlackTreeWithResizeLibTest
 
 # Run gas benchmarks
 forge test --match-contract MappingGasTest -vv
@@ -126,6 +184,8 @@ forge test --match-contract MappingGasTest -vv
 
 The test suite includes:
 
+**RedBlackTreeKV Tests:**
+
 - ✅ Basic CRUD operations
 - ✅ Edge cases (zero keys, max values)
 - ✅ Multiple value operations
@@ -134,14 +194,40 @@ The test suite includes:
 - ✅ Fuzz testing with random inputs
 - ✅ Gas consumption benchmarks
 
+**RedBlackTreeWithResizeKV Tests:**
+
+- ✅ All basic KV operations with resize functionality
+- ✅ Storage capacity management and pre-allocation
+- ✅ Resize operations (expand, shrink, same capacity)
+- ✅ Data preservation during resize operations
+- ✅ Error handling for invalid resize operations
+- ✅ Resize with mixed insert/delete operations
+- ✅ Fuzz testing for resize capacity variations
+
+**RedBlackTreeWithResizeLib Tests:**
+
+- ✅ Core Red-Black Tree operations with resize support
+- ✅ Storage size tracking and capacity management
+- ✅ Tree balancing with dynamic storage allocation
+- ✅ Error cases for tree size limits and invalid operations
+
 ## Use Cases
 
 This implementation is ideal for:
 
-- **Order Books**: Frequent order insertions and cancellations
-- **Gaming**: Player inventory systems with item trading
-- **DeFi Protocols**: Position management with frequent updates
-- **NFT Marketplaces**: Listing and delisting operations
+- **Order Books**: Frequent order insertions and cancellations with predictable volume patterns
+- **Gaming**: Player inventory systems with item trading and known capacity requirements
+- **DeFi Protocols**: Position management with frequent updates and batch operations
+- **NFT Marketplaces**: Listing and delisting operations with seasonal volume spikes
+- **Data Analytics**: Time-series data storage with known dataset sizes
+- **Batch Processing**: Systems that process large batches of data with predictable patterns
+
+**When to use RedBlackTreeWithResizeKV:**
+
+- You know the approximate maximum number of elements in advance
+- You need to optimize for gas costs during high-frequency operations
+- Your application has predictable usage patterns or batch processing requirements
+- You want to avoid gas spikes during storage allocation
 
 ## License
 

src/lib/RedBlackTreeWithResizeLib.sol

@@ -136,6 +136,7 @@ library RedBlackTreeWithResizeLib {
     /// Returns a non-zero error code upon failure instead of reverting.
     function tryResize(Tree storage tree, uint256 newCapacity) internal returns (uint256 err) {
         uint256 currentSize = size(tree);
+        uint256 oldCapacity = storageSize(tree);
         if (newCapacity > _BITMASK_KEY) return ERROR_TREE_IS_FULL;
         if (newCapacity < currentSize) return ERROR_INVALID_STORAGE_SIZE;
 
@@ -158,6 +159,14 @@ library RedBlackTreeWithResizeLib {
                 sstore(or(nodes, index), 1)
                 sstore(or(_BIT_FULL_VALUE_SLOT, or(nodes, index)), 1)
             }
+
+            // Release storage slots for smaller capacity
+            start := add(newCapacity, 1)
+            end := oldCapacity
+            for { let index := start } iszero(gt(index, end)) { index := add(index, 1) } {
+                sstore(or(nodes, index), 0)
+                sstore(or(_BIT_FULL_VALUE_SLOT, or(nodes, index)), 0)
+            }
         }
         return 0;
     }

test/RedBlackTreeWithResize.sol

@@ -7,7 +7,7 @@ import {LibSort} from "../src/lib/LibSort.sol";
 import {LibPRNG} from "../src/lib/LibPRNG.sol";
 import {RedBlackTreeWithResizeLib} from "../src/lib/RedBlackTreeWithResizeLib.sol";
 
-contract RedBlackTreeLibTest is SoladyTest {
+contract RedBlackTreeWithResizeLibTest is SoladyTest {
     using RedBlackTreeWithResizeLib for *;
     using LibPRNG for *;