init

Author: xiaozzz

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  check:
+    name: Foundry project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Show Forge version
+        run: |
+          forge --version
+
+      - name: Run Forge fmt
+        run: |
+          forge fmt --check
+        id: fmt
+
+      - name: Run Forge build
+        run: |
+          forge build --sizes
+        id: build
+
+      - name: Run Forge tests
+        run: |
+          forge test -vvv
+        id: test

.gitignore

@@ -0,0 +1,14 @@
+# Compiler files
+cache/
+out/
+
+# Ignores development broadcast logs
+!/broadcast
+/broadcast/*/31337/
+/broadcast/**/dry-run/
+
+# Docs
+docs/
+
+# Dotenv file
+.env

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/forge-std"]
+	path = lib/forge-std
+	url = https://github.com/foundry-rs/forge-std

README.md

@@ -0,0 +1,148 @@
+# RedBlackTree KV Demo
+
+A demonstration of a gas-efficient key-value store implementation using Red-Black Tree data structure in Solidity. This project showcases how Red-Black Trees can be more gas-efficient than traditional mapping-based storage when frequently adding and removing values.
+
+## Overview
+
+This project implements a Red-Black Tree based key-value store (`RedBlockTreeKV`) that stores complex value structures efficiently. The implementation is particularly beneficial for use cases involving frequent insertions and deletions, as it reuses storage slots and minimizes gas consumption.
+
+The Red-Black Tree implementation is based on [Solady's RedBlackTreeLib](https://github.com/vectorized/solady/blob/main/src/utils/RedBlackTreeLib.sol). In this example, we modified the `remove` function to prevent deleting storage when removing nodes, enabling storage slot reuse for subsequent insertions.
+
+### Key Features
+
+- **Gas-Efficient Storage**: Reuses storage slots when items are deleted, leading to significant gas savings on subsequent insertions
+- **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
+
+### Gas Performance
+
+Based on benchmark tests with 1,000 operations:
+
+**RedBlackTreeKV:**
+
+- Cold Insert: ~188,984 gas
+- Hot Insert (reusing deleted slot): ~13,250 gas ⚡
+- Delete: ~12,876 gas
+
+**Traditional Mapping:**
+
+- Insert: ~135,350 gas
+- Delete: ~1,529 gas
+
+The Red-Black Tree implementation shows **90% gas reduction** for hot insertions compared to cold insertions, making it highly efficient for applications with frequent add/remove patterns.
+
+> **Note for MegaETH**: On MegaETH where SSTORE operations cost significantly more than standard EVM, the gas efficiency advantage of RedBlackTreeKV becomes even more pronounced due to its storage slot reuse optimization.
+
+## Project Structure
+
+```
+src/
+├── RedBlockTreeKV.sol      # Main KV store implementation
+├── MappingKV.sol          # Traditional mapping implementation for comparison
+└── lib/
+    ├── RedBlackTreeLib.sol # Red-Black Tree data structure library
+    └── Value.sol          # Value struct definition
+
+test/
+├── RedBlockTreeKV.t.sol     # Comprehensive unit tests
+└── RedBlockTreeKVGas.t.sol  # Gas benchmark tests
+```
+
+## Value Structure
+
+The KV store works with `ValueLib.Value` structs:
+
+```solidity
+struct Value {
+    bytes32 slot1;  // 32 bytes
+    uint256 slot2;  // 32 bytes
+    int256 slot3;   // 32 bytes
+    bytes32 slot4;  // 32 bytes
+    uint256 slot5;  // 32 bytes
+    address slot6;  // 20 bytes
+}
+// Total: 192 bytes (6 storage slots)
+```
+
+## Usage
+
+### Basic Operations
+
+```solidity
+RedBlockTreeKV kv = new RedBlockTreeKV();
+
+// Create a value
+ValueLib.Value memory value = ValueLib.Value({
+    slot1: bytes32(uint256(100)),
+    slot2: 100,
+    slot3: int256(100),
+    slot4: bytes32(uint256(100)),
+    slot5: 100,
+    slot6: address(uint160(100))
+});
+
+// Set value
+kv.setValue(1, value);
+
+// Get value
+ValueLib.Value memory retrieved = kv.getValue(1);
+
+// Delete value
+kv.deleteValue(1);
+
+// Get all keys (sorted)
+uint256[] memory keys = kv.values();
+```
+
+### Constraints
+
+- **No Zero Keys**: Keys cannot be 0 (will revert with `ValueIsEmpty()`)
+- **No Duplicate Keys**: Attempting to set an existing key will revert with `ValueAlreadyExists()`
+- **Key Must Exist for Deletion**: Deleting non-existent keys will revert with `ValueDoesNotExist()`
+
+## Development
+
+### Build
+
+```shell
+forge build
+```
+
+### Test
+
+```shell
+# Run all tests
+forge test
+
+# Run unit tests only
+forge test --match-contract RedBlockTreeKVTest
+
+# Run gas benchmarks
+forge test --match-contract MappingGasTest -vv
+```
+
+### Test Coverage
+
+The test suite includes:
+
+- ✅ Basic CRUD operations
+- ✅ Edge cases (zero keys, max values)
+- ✅ Multiple value operations
+- ✅ Delete and reuse scenarios
+- ✅ Large dataset handling (100+ items)
+- ✅ Fuzz testing with random inputs
+- ✅ Gas consumption benchmarks
+
+## 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
+
+## License
+
+MIT

foundry.toml

@@ -0,0 +1,9 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+optimizer = true
+optimizer_runs = 200
+solc = "0.8.30"
+
+# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

lib/forge-std

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.4;
+
+import {ValueLib} from "./lib/Value.sol";
+
+// A simple kv example. It is gas-consuming if frequently add & remove.
+contract MappingKV {
+    // a mapping kv
+    mapping(uint256 => ValueLib.Value) public kv;
+
+    function setValue(uint256 key, ValueLib.Value memory value) public {
+        kv[key] = value;
+    }
+
+    function getValue(uint256 key) public view returns (ValueLib.Value memory) {
+        return kv[key];
+    }
+
+    function deleteValue(uint256 key) public {
+        delete kv[key];
+    }
+}

src/MappingKV.sol

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.4;
+
+import {RedBlackTreeLib} from "./lib/RedBlackTreeLib.sol";
+import {ValueLib} from "./lib/Value.sol";
+
+// A simple RBT kv example. It is gas-efficient if frequently add & remove.
+contract RedBlockTreeKV {
+    uint256 private constant _DATA_SLOT_SEED = 0xdeadbeef; // Arbitrary unique seed
+    uint256 private constant _SLOTS_PER_POSITION = ValueLib.SLOTS_PER_POSITION; // Dense slots per value
+
+    RedBlackTreeLib.Tree public tree;
+
+    using RedBlackTreeLib for RedBlackTreeLib.Tree;
+
+    function setValue(uint256 key, ValueLib.Value memory value) public {
+        tree.insert(key);
+        bytes32 ptr = tree.find(key);
+        (, uint256 index) = _unpack(ptr); // Extract dense node index
+        uint256 dataBase = _dataBase();
+        uint256 valueSlot = dataBase + index * _SLOTS_PER_POSITION;
+        /// @solidity memory-safe-assembly
+        assembly {
+            sstore(valueSlot, mload(value))
+            sstore(add(valueSlot, 1), mload(add(value, 0x20)))
+            sstore(add(valueSlot, 2), mload(add(value, 0x40)))
+            sstore(add(valueSlot, 3), mload(add(value, 0x60)))
+            sstore(add(valueSlot, 4), mload(add(value, 0x80)))
+            sstore(add(valueSlot, 5), mload(add(value, 0xa0)))
+        }
+    }
+
+    function getValue(uint256 key) public view returns (ValueLib.Value memory) {
+        bytes32 ptr = tree.find(key);
+        (, uint256 index) = _unpack(ptr); // Extract dense node index
+        uint256 dataBase = _dataBase();
+        uint256 valueSlot = dataBase + index * _SLOTS_PER_POSITION;
+        ValueLib.Value memory value;
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(value, sload(valueSlot))
+            mstore(add(value, 0x20), sload(add(valueSlot, 1)))
+            mstore(add(value, 0x40), sload(add(valueSlot, 2)))
+            mstore(add(value, 0x60), sload(add(valueSlot, 3)))
+            mstore(add(value, 0x80), sload(add(valueSlot, 4)))
+            mstore(add(value, 0xa0), sload(add(valueSlot, 5)))
+        }
+        return value;
+    }
+
+    function deleteValue(uint256 key) public {
+        bytes32 ptr = tree.find(key);
+        (, uint256 deletedIndex) = _unpack(ptr); // Extract dense node index
+        uint256 dataBase = _dataBase();
+        uint256 deletedSlot = dataBase + deletedIndex * _SLOTS_PER_POSITION;
+
+        uint256 treeSize = tree.size();
+        uint256 lastIndex = treeSize;
+        bool needsCopy = (deletedIndex != lastIndex);
+        uint256 lastSlot = dataBase + lastIndex * _SLOTS_PER_POSITION;
+
+        tree.remove(key);
+
+        if (needsCopy) {
+            /// @solidity memory-safe-assembly
+            assembly {
+                for { let i := 0 } lt(i, 6) { i := add(i, 1) } { sstore(add(deletedSlot, i), sload(add(lastSlot, i))) }
+            }
+        }
+    }
+
+    // Helper: Compute data base slot (keccak-based, like tree nodes but unique seed)
+    function _dataBase() internal pure returns (uint256 slotBase) {
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(0x20, tree.slot)
+            mstore(0x00, _DATA_SLOT_SEED)
+            slotBase := keccak256(0x00, 0x40)
+        }
+    }
+
+    // Helper: Unpack pointer (copied from lib private _unpack for convenience)
+    function _unpack(bytes32 ptr) internal pure returns (uint256 nodes, uint256 key) {
+        /// @solidity memory-safe-assembly
+        assembly {
+            nodes := shl(32, shr(32, ptr)) // _NODES_SLOT_SHIFT == 32
+            key := and(0x7fffffff, ptr) // _BITMASK_KEY == (1 << 31) - 1
+        }
+    }
+
+    function values() public view returns (uint256[] memory) {
+        return tree.values();
+    }
+}