Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ A demonstration of a gas-efficient key-value store implementation using Red-Blac

## 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.
This project implements a Red-Black Tree based key-value store (`RedBlackTreeKV`) 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.

Expand Down Expand Up @@ -38,15 +38,15 @@ The Red-Black Tree implementation shows **90% gas reduction** for hot insertions

```
src/
├── RedBlockTreeKV.sol # Main KV store implementation
├── RedBlackTreeKV.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
├── RedBlackTreeKV.t.sol # Comprehensive unit tests
└── RedBlackTreeKVGas.t.sol # Gas benchmark tests
```

## Value Structure
Expand All @@ -70,7 +70,7 @@ struct Value {
### Basic Operations

```solidity
RedBlockTreeKV kv = new RedBlockTreeKV();
RedBlackTreeKV kv = new RedBlackTreeKV();

// Create a value
ValueLib.Value memory value = ValueLib.Value({
Expand Down Expand Up @@ -116,7 +116,7 @@ forge build
forge test

# Run unit tests only
forge test --match-contract RedBlockTreeKVTest
forge test --match-contract RedBlackTreeKVTest

# Run gas benchmarks
forge test --match-contract MappingGasTest -vv
Expand Down
2 changes: 1 addition & 1 deletion src/RedBlockTreeKV.sol → src/RedBlackTreeKV.sol
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ 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 {
contract RedBlackTreeKV {
uint256 private constant _DATA_SLOT_SEED = 0xdeadbeef; // Arbitrary unique seed
uint256 private constant _SLOTS_PER_POSITION = ValueLib.SLOTS_PER_POSITION; // Dense slots per value

Expand Down
8 changes: 4 additions & 4 deletions test/RedBlockTreeKV.t.sol → test/RedBlackTreeKV.t.sol
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
pragma solidity ^0.8.30;

import {Test, console} from "forge-std/Test.sol";
import {RedBlockTreeKV} from "../src/RedBlockTreeKV.sol";
import {RedBlackTreeKV} from "../src/RedBlackTreeKV.sol";
import {ValueLib} from "../src/lib/Value.sol";
import {RedBlackTreeLib} from "../src/lib/RedBlackTreeLib.sol";

contract RedBlockTreeKVTest is Test {
RedBlockTreeKV public redBlockTreeKV;
contract RedBlackTreeKVTest is Test {
RedBlackTreeKV public redBlockTreeKV;

function setUp() public {
redBlockTreeKV = new RedBlockTreeKV();
redBlockTreeKV = new RedBlackTreeKV();
}

function generateValue(uint256 value) internal pure returns (ValueLib.Value memory) {
Expand Down
6 changes: 3 additions & 3 deletions test/RedBlockTreeKVGas.t.sol → test/RedBlackTreeKVGas.t.sol
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@
pragma solidity ^0.8.30;

import {Test, console} from "forge-std/Test.sol";
import {RedBlockTreeKV} from "../src/RedBlockTreeKV.sol";
import {RedBlackTreeKV} from "../src/RedBlackTreeKV.sol";
import {MappingKV} from "../src/MappingKV.sol";
import {ValueLib} from "../src/lib/Value.sol";

contract MappingGasTest is Test {
uint256 private constant _INSERT_COUNT = 1000;
RedBlockTreeKV public redBlockTreeKV;
RedBlackTreeKV public redBlockTreeKV;
MappingKV public mappingKV;

function setUp() public {
redBlockTreeKV = new RedBlockTreeKV();
redBlockTreeKV = new RedBlackTreeKV();
mappingKV = new MappingKV();
}

Expand Down