Source

Storage Architecture

Y Protocol uses RocksDB with column families for storage, atomic operations, and crash recovery capabilities.

RocksDB
6 Column Families
Atomic Operations
WAL Support

RocksDB Implementation

Column Family Structure
Organized storage with dedicated column families for performance
pub const CF_METADATA: &str = "metadata";        // Chain metadata
pub const CF_ACCOUNTS: &str = "accounts";        // Account states
pub const CF_TRANSACTIONS: &str = "transactions"; // Transaction data
pub const CF_VALIDATORS: &str = "validators";    // Validator info
pub const CF_BLOCKS: &str = "blocks";           // Block data
pub const CF_CONSENSUS: &str = "consensus";     // Consensus state
Source: /crates/consensus/src/storage/db.rs
Metadata

Network configuration and chain state information

Chain Height:
Current block
Network ID:
Genesis hash
Accounts

Account balances, nonces, and transaction history

Balance Storage:
yu precision
Nonce Tracking:
Anti-replay
Transactions

Transaction history with status and block references

Full History:
All transactions
Status Tracking:
Confirmed/Pending
Validators

Validator information, stakes, and performance metrics

Stake Amounts:
Current stakes
Performance:
Vote history
Blocks

Blockchain data with headers and transaction lists

Block Headers:
Metadata
Tx References:
Linked data
Consensus

Consensus state, validator votes, and proposal tracking

Vote Records:
Per height
Proposals:
Active/Historic

Key Encoding Strategy

Binary Codec Implementation
Key encoding for range scans and lookups
impl BinaryCodec {
    /// Encode block key for height-based ordering
    pub fn encode_block_key(height: u64) -> Vec<u8> {
        format!("block_{:020}", height).into_bytes()
    }

    /// Encode transaction key for lookups
    pub fn encode_transaction_key(tx_id: &str) -> StorageResult<Vec<u8>> {
        Ok(format!("tx_{}", tx_id).into_bytes())
    }

    /// Encode validator key for validator operations
    pub fn encode_validator_key(validator_id: &str) -> StorageResult<Vec<u8>> {
        Ok(format!("val_{}", validator_id).into_bytes())
    }
}
Height-Based Ordering

Block keys use zero-padded height for range scans

block_00000000000000001000
Prefix-Based Lookup

Transaction and validator keys use prefixes for fast filtering

tx_abc123... / val_validator1
Range Scan Optimization

Key design enables iterator-based processing

block_* → Sequential scan

Storage Features

Performance Features
Cache Size
512MB default
Compression
LZ4/Snappy/ZSTD
Memory Mapping
Enabled
Bloom Filters
Per CF

Optimized for both read and write performance with configurable caching.

Reliability Features
Write-Ahead Logging
Enabled
Atomic Batches
Supported
Crash Recovery
Automatic
Backup/Restore
Built-in

Data protection with crash recovery and backup capabilities.

Data Encoding

Binary Serialization
Data encoding using bincode
Serialization
bincode
Deterministic
Yes
Compact
Binary format

Deterministic binary encoding ensures consistent storage across nodes.

Version Compatibility
Forward/backward compatibility handling
Schema Evolution
Supported
Version Tags
Per record
Migration
Automatic

Handles protocol upgrades while maintaining data integrity.

Performance Characteristics

Lookups
O(log n)
Key lookup complexity
Range Scans
Efficient
Iterator-based processing
Compression
~60%
Average compression ratio
Cache Hit
~90%
Typical cache hit rate

Configuration

RocksDB Configuration Example
Database configuration
[database]
cache_size = "512MB"
max_open_files = 1000
compression = "lz4"
enable_wal = true
wal_size_limit = "64MB"
max_background_jobs = 4

[column_families.blocks]
block_cache_size = "128MB"
bloom_filter_bits = 10
compaction_style = "level"

[column_families.transactions]
block_cache_size = "256MB"
bloom_filter_bits = 12
compaction_style = "universal"