Package com.privatechain.core.spi

Interface BlockchainStorage

All Known Implementing Classes:
FileSystemStorage, InMemoryStorage, LevelDBStorage, RocksDBStorage
public interface BlockchainStorage
Service Provider Interface (SPI) for persistent block storage.

Implementations must be thread-safe for concurrent reads; writes must be serialized (NFR-REL-01, FR-STOR-06). The library ships four built-in implementations in the blockchain-storage module:

  • InMemoryStorage — HashMap-backed, for testing (FR-STOR-02)
  • LevelDBStorage — crash-safe persistent storage (FR-STOR-03)
  • RocksDBStorage — high write-throughput persistent storage (FR-STOR-04)
  • FileSystemStorage — one JSON file per block, zero native deps (FR-STOR-05)

Contract

  • Blocks are stored by their integer index (unique per chain).
  • saveBlock(Block) is idempotent: saving the same block twice must not throw; the second call is a no-op or an overwrite of identical data.
  • loadAll() must return blocks in ascending index order.
Since:
1.0.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    chainHeight()
    Returns the current number of stored blocks (i.e., the latest block index + 1).
    void
    deleteAll()
    Removes all stored blocks from the storage medium.
    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 index.
    Optional<Block>
    loadBlockByHash(String hash)
    Retrieves a block by its SHA-256 hash.
    void
    saveBlock(Block block)
    Persists a block to the underlying storage medium.

  • Method Details

    • saveBlock

      void saveBlock(Block block)
      Persists a block to the underlying storage medium.

      Must be atomic: either the block is fully written or the storage state is unchanged (no partial writes). Implementations backed by LevelDB or RocksDB satisfy this by writing inside an atomic batch.

      Parameters:
      block - the block to persist (non-null)
      Throws:
      BlockValidationException - if the write fails

    • loadBlock

      Block loadBlock(int index)
      Retrieves a block by its index.
      Parameters:
      index - block index (≥ 0)
      Returns:
      the block at the given index
      Throws:
      NoSuchElementException - if no block exists at index

    • loadBlockByHash

      Optional<Block> loadBlockByHash(String hash)
      Retrieves a block by its SHA-256 hash.
      Parameters:
      hash - hex-encoded block hash (non-null)
      Returns:
      an Optional containing the block, or empty if not found

    • loadAll

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

      For large chains callers should prefer iterating via index ranges rather than loading the full chain into memory at once.

      Returns:
      non-null, possibly empty, ordered list of all blocks

    • exists

      boolean exists(String hash)
      Returns true if a block with the given hash is stored.
      Parameters:
      hash - hex-encoded block hash to look up (non-null)
      Returns:
      true if present

    • chainHeight

      int chainHeight()
      Returns the current number of stored blocks (i.e., the latest block index + 1).
      Returns:
      number of blocks (≥ 0)

    • deleteAll

      void deleteAll()
      Removes all stored blocks from the storage medium.

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