Package com.privatechain.storage.rocksdb

Class RocksDBStorage

java.lang.Object
com.privatechain.storage.rocksdb.RocksDBStorage
All Implemented Interfaces:
BlockchainStorage, AutoCloseable
public final class RocksDBStorage extends Object implements BlockchainStorage, AutoCloseable
High write-throughput, crash-safe BlockchainStorage implementation backed by RocksDB.

RocksDB is Facebook's LSM-tree storage engine optimized for high-write workloads on SSDs. It provides write-ahead logging (WAL) and crash recovery (NFR-REL-01, FR-STOR-04). Each block is stored under a big-endian 4-byte integer key, serialized to JSON via BlockSerializer.

Key layout

 Key  : big-endian 4-byte block index (e.g., block 7 → 0x00_00_00_07)
 Value: UTF-8 JSON of the Block object

Performance tuning

The default configuration enables:

  • Snappy compression to reduce disk footprint
  • 64 MB write buffer for batching sequential writes
  • Bloom filters on block-based table to speed up point reads

Thread safety

RocksDB is internally thread-safe for concurrent reads. This class adds an additional ReentrantReadWriteLock to serialize writes and protect the close() method from concurrent access.

Lifecycle


 try (RocksDBStorage storage = new RocksDBStorage("/data/chain-rocks")) {
     BlockchainNode node = BlockchainConfig.builder()
         .storage(storage)
         .build();
     node.start();
 }
Since:
1.0.0
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    RocksDBStorage(String dataDirectory)
    Opens (or creates) a RocksDB database at the given directory path.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    chainHeight()
    Returns the number of stored blocks by counting block-keyed entries.
    void
    close()
    Closes the RocksDB database and releases all native resources.
    void
    deleteAll()
    Removes all block entries from the RocksDB store.
    boolean
    exists(String hash)
    Returns true if a block with the given hash is stored.
    List<Block>
    loadAll()
    Returns all stored blocks in ascending index order.
    Block
    loadBlock(int index)
    Retrieves a block by its zero-based index.
    Optional<Block>
    loadBlockByHash(String hash)
    Searches for a block by its SHA-256 hash.
    void
    saveBlock(Block block)
    Persists a block atomically using a RocksDB WriteBatch.
    String
    toString()
    Returns a human-readable description of this storage instance.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • RocksDBStorage

      public RocksDBStorage(String dataDirectory)
      Opens (or creates) a RocksDB database at the given directory path.

      The database directory is created automatically if it does not exist. If the database is already locked by another process, the constructor will throw immediately.

      Parameters:
      dataDirectory - path to the directory where RocksDB files will be stored
      Throws:
      NullPointerException - if dataDirectory is null
      IllegalArgumentException - if dataDirectory is blank
      BlockValidationException - if the database cannot be opened

  • Method Details

    • saveBlock

      public void saveBlock(Block block)
      Persists a block atomically using a RocksDB WriteBatch.

      Write batches in RocksDB are atomic: either the entire batch is applied or none of it is, satisfying the atomicity requirement of BlockchainStorage.saveBlock(com.privatechain.core.model.Block).

      Specified by:
      saveBlock in interface BlockchainStorage
      Parameters:
      block - the block to persist (non-null)
      Throws:
      NullPointerException - if block is null
      BlockValidationException - if the write fails

    • loadBlock

      public Block loadBlock(int index)
      Retrieves a block by its zero-based index.
      Specified by:
      loadBlock in interface BlockchainStorage
      Parameters:
      index - block index (≥ 0)
      Returns:
      the deserialized Block
      Throws:
      NoSuchElementException - if no block exists at index
      BlockValidationException - if deserialization or hash verification fails

    • loadBlockByHash

      public Optional<Block> loadBlockByHash(String hash)
      Searches for a block by its SHA-256 hash.

      Performs a sequential scan — suitable for moderate chain sizes. For very large chains a secondary hash→index should be maintained.

      Specified by:
      loadBlockByHash in interface BlockchainStorage
      Parameters:
      hash - hex-encoded block hash (non-null)
      Returns:
      an Optional containing the matching block, or empty if absent
      Throws:
      NullPointerException - if hash is null

    • loadAll

      public List<Block> loadAll()
      Returns all stored blocks in ascending index order.

      RocksDB's lexicographic ordering of big-endian keys provides natural ascending order without any post-scan sort.

      Specified by:
      loadAll in interface BlockchainStorage
      Returns:
      non-null, ordered list (maybe empty)

    • exists

      public boolean exists(String hash)
      Returns true if a block with the given hash is stored.
      Specified by:
      exists in interface BlockchainStorage
      Parameters:
      hash - hex-encoded block hash (non-null)
      Returns:
      true if present
      Throws:
      NullPointerException - if hash is null

    • chainHeight

      public int chainHeight()
      Returns the number of stored blocks by counting block-keyed entries.
      Specified by:
      chainHeight in interface BlockchainStorage
      Returns:
      block count (≥ 0)

    • deleteAll

      public void deleteAll()
      Removes all block entries from the RocksDB store.

      Warning: This operation is irreversible. Intended for testing and chain-reset scenarios only.

      Specified by:
      deleteAll in interface BlockchainStorage

    • close

      public void close()
      Closes the RocksDB database and releases all native resources.

      Must be called when the owning node shuts down to flush the write buffer and release the file lock. Subsequent calls are idempotent.

      Specified by:
      close in interface AutoCloseable

    • toString

      public String toString()
      Returns a human-readable description of this storage instance.
      Overrides:
      toString in class Object
      Returns:
      string representation