refactor: rename store to database

Author: DracoLi

x/blockdb/README.md

@@ -2,16 +2,14 @@
 
 BlockDB is a specialized storage system designed for blockchain blocks. It provides O(1) write performance with support for parallel operations. Unlike general-purpose key-value stores like LevelDB that require periodic compaction, BlockDB's append-only design ensures consistently fast writes without the overhead of background maintenance operations.
 
-## Key Functionalities (Needs Review)
+## Key Functionalities
 
 - **O(1) Performance**: Both reads and writes complete in constant time
 - **Parallel Operations**: Multiple threads can read and write blocks concurrently without blocking
-- **Flexible Write Ordering**: Supports out-of-order block writes for efficient synchronization
-- **Configurable Durability**: Optional `syncToDisk` mode guarantees immediate recoverability at the cost of performance
+- **Flexible Write Ordering**: Supports out-of-order block writes for bootstrapping
+- **Configurable Durability**: Optional `syncToDisk` mode guarantees immediate recoverability
 - **Automatic Recovery**: Detects and recovers unindexed blocks after unclean shutdowns
-- **Data Integrity**: Checksums verify block data on every read
-- **No Maintenance Required**: Append-only design eliminates the need for compaction or reorganization
-- **Progress Tracking**: Maintains maximum contiguous height for sync status
+- **Data Integrity**: Checksums verify block data on reads
 
 ## Architecture
 
@@ -27,6 +25,7 @@ BlockDB uses two file types: index files and data files. The index file maps blo
 │ - Min Height    │  │      │ - Data          │
 │ - MCH           │  │      ├─────────────────┤
 │ - Data Size     │  │      │ Block 2         │
+│ - ...           │  │      │                 │
 ├─────────────────┤  │  ┌──>│ - Header        │
 │ Entry[0]        │  │  │   │ - Data          │
 │ - Offset ───────┼──┘  │   ├─────────────────┤
@@ -101,7 +100,7 @@ BlockDB is strictly append-only with no support for deletions. This aligns with
 - Straightforward recovery logic
 - No compaction overhead
 
-**Trade-off**: Overwriting a block leaves the old data as unreferenced "dead" space. However, since blockchain blocks are immutable and rarely overwritten (only during reorgs), this trade-off has minimal impact in practice.
+**Trade-off**: Overwriting a block leaves the old data as unreferenced "dead" space. However, since blocks are immutable and rarely overwritten (only during reorgs), this trade-off has minimal impact in practice.
 
 #### Fixed-Size Index Entries
 
@@ -164,26 +163,26 @@ BlockDB uses a reader-writer lock for overall thread safety, with atomic operati
 
 ## Usage
 
-### Creating a Store
+### Creating a Database
 
 ```go
 import "github.com/ava-labs/avalanchego/x/blockdb"
 
-opts := blockdb.DefaultStoreOptions()
-opts.MinimumHeight = 1
+config := blockdb.DefaultDatabaseOptions()
+config.MinimumHeight = 1
 
-store, err := blockdb.NewStore(
+db, err := blockdb.New(
     "/path/to/index",  // Index directory
     "/path/to/data",   // Data directory
     true,              // Sync to disk
     false,             // Don't truncate existing data
-    opts,
+    config,
     logger,
 )
 if err != nil {
     return err
 }
-defer store.Close()
+defer db.Close()
 ```
 
 ### Writing and Reading Blocks
@@ -192,17 +191,17 @@ defer store.Close()
 // Write a block
 height := uint64(100)
 blockData := []byte("block data...")
-err := store.WriteBlock(height, blockData)
+err := db.WriteBlock(height, blockData)
 
 // Read a block
-blockData, err := store.ReadBlock(height)
+blockData, err := db.ReadBlock(height)
 if err == blockdb.ErrBlockNotFound {
     // Block doesn't exist at this height
 }
 
-// Query store state
-maxContiguous := store.MaxContiguousHeight()
-minHeight := store.MinHeight()
+// Query database state
+maxContiguous := db.MaxContiguousHeight()
+minHeight := db.MinHeight()
 ```
 
 ## TODO

x/blockdb/block.go

@@ -21,7 +21,7 @@ var (
 
 // blockHeader is prepended to each block in the data file.
 type blockHeader struct {
-	Height uint64
+	Height uint64 // todo: can this be omitted? currently only used for verification
 	// Size of the raw block data (excluding this blockHeader).
 	Size     uint64
 	Checksum uint64
@@ -49,12 +49,12 @@ func (bh *blockHeader) UnmarshalBinary(data []byte) error {
 
 // WriteBlock inserts a block into the store at the given height.
 // Returns an error if the store is closed, the block is empty, or the write fails.
-func (s *Store) WriteBlock(height BlockHeight, block Block) error {
+func (s *Database) WriteBlock(height BlockHeight, block Block) error {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
 	if s.closed {
-		return ErrStoreClosed
+		return ErrDatabaseClosed
 	}
 
 	if len(block) == 0 {
@@ -95,12 +95,12 @@ func (s *Store) WriteBlock(height BlockHeight, block Block) error {
 
 // ReadBlock retrieves a block by its height.
 // Returns the block data or an error if not found or block data is corrupted.
-func (s *Store) ReadBlock(height BlockHeight) (Block, error) {
+func (s *Database) ReadBlock(height BlockHeight) (Block, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
 	if s.closed {
-		return nil, ErrStoreClosed
+		return nil, ErrDatabaseClosed
 	}
 
 	indexEntry, err := s.readIndexEntry(height)
@@ -122,7 +122,7 @@ func (s *Store) ReadBlock(height BlockHeight) (Block, error) {
 	return s.readAndVerifyBlockData(indexEntry, bh)
 }
 
-func (s *Store) readAndVerifyBlockHeader(indexEntry IndexEntry, expectedHeight BlockHeight) (blockHeader, error) {
+func (s *Database) readAndVerifyBlockHeader(indexEntry IndexEntry, expectedHeight BlockHeight) (blockHeader, error) {
 	var bh blockHeader
 	dataHeaderBuf := make([]byte, sizeOfBlockHeader)
 	_, err := s.dataFile.ReadAt(dataHeaderBuf, int64(indexEntry.Offset))
@@ -143,7 +143,7 @@ func (s *Store) readAndVerifyBlockHeader(indexEntry IndexEntry, expectedHeight B
 	return bh, nil
 }
 
-func (s *Store) readAndVerifyBlockData(indexEntry IndexEntry, bh blockHeader) (Block, error) {
+func (s *Database) readAndVerifyBlockData(indexEntry IndexEntry, bh blockHeader) (Block, error) {
 	blockData := make(Block, bh.Size)
 	actualDataOffset := indexEntry.Offset + sizeOfBlockHeader
 	if actualDataOffset < indexEntry.Offset {
@@ -167,7 +167,7 @@ func calculateChecksum(data []byte) uint64 {
 	return xxhash.Sum64(data)
 }
 
-func (s *Store) writeBlockAtOffset(offset uint64, bh blockHeader, block Block) error {
+func (s *Database) writeBlockAtOffset(offset uint64, bh blockHeader, block Block) error {
 	headerBytes, err := bh.MarshalBinary()
 	if err != nil {
 		return fmt.Errorf("failed to serialize block header: %w", err)
@@ -192,7 +192,7 @@ func (s *Store) writeBlockAtOffset(offset uint64, bh blockHeader, block Block) e
 	return nil
 }
 
-func (s *Store) updateBlockHeights(writtenBlockHeight uint64) error {
+func (s *Database) updateBlockHeights(writtenBlockHeight uint64) error {
 	// update max contiguous height
 	var prevContiguousCandidate uint64
 	if writtenBlockHeight == s.header.MinBlockHeight {
@@ -244,7 +244,7 @@ func (s *Store) updateBlockHeights(writtenBlockHeight uint64) error {
 	return nil
 }
 
-func (s *Store) allocateBlockSpace(sizeWithDataHeader uint64) (writeDataOffset uint64, err error) {
+func (s *Database) allocateBlockSpace(sizeWithDataHeader uint64) (writeDataOffset uint64, err error) {
 	maxDataFileSize := s.header.MaxDataFileSize
 
 	for {

x/blockdb/blockdb.go

@@ -4,8 +4,8 @@ import (
 	"fmt"
 )
 
-// StoreOptions contains optional configuration parameters for BlockDB.
-type StoreOptions struct {
+// DatabaseConfig contains configuration parameters for BlockDB.
+type DatabaseConfig struct {
 	// MinimumHeight is the lowest block height the store will track (must be >= 1).
 	MinimumHeight uint64
 
@@ -16,17 +16,17 @@ type StoreOptions struct {
 	CheckpointInterval uint64
 }
 
-// DefaultStoreOptions returns the default options for BlockDB.
-func DefaultStoreOptions() StoreOptions {
-	return StoreOptions{
+// DefaultDatabaseConfig returns the default options for BlockDB.
+func DefaultDatabaseConfig() DatabaseConfig {
+	return DatabaseConfig{
 		MinimumHeight:      1,
 		MaxDataFileSize:    1 << 31, // Default to 2GB
 		CheckpointInterval: 1024,
 	}
 }
 
 // Validate checks if the store options are valid.
-func (opts StoreOptions) Validate() error {
+func (opts DatabaseConfig) Validate() error {
 	if opts.MinimumHeight == 0 {
 		return fmt.Errorf("%w: MinimumHeight cannot be 0, must be >= 1", ErrInvalidBlockHeight)
 	}

x/blockdb/config.go

@@ -23,11 +23,11 @@ type BlockHeight = uint64
 // Block defines the type for block data.
 type Block = []byte
 
-// Store is a collection of blockchain blocks. It provides methods to read, write, and manage blocks on disk.
-type Store struct {
+// Database is a collection of blockchain blocks. It provides methods to read, write, and manage blocks on disk.
+type Database struct {
 	indexFile *os.File
 	dataFile  *os.File
-	options   StoreOptions
+	options   DatabaseConfig
 	header    IndexFileHeader
 	log       logging.Logger
 
@@ -45,7 +45,7 @@ type Store struct {
 	maxContiguousHeight atomic.Uint64
 }
 
-func (s *Store) openOrCreateFiles(indexDir, dataDir string, truncate bool) error {
+func (s *Database) openOrCreateFiles(indexDir, dataDir string, truncate bool) error {
 	indexPath := filepath.Join(indexDir, indexFileName)
 	dataPath := filepath.Join(dataDir, dataFileName)
 
@@ -75,7 +75,7 @@ func (s *Store) openOrCreateFiles(indexDir, dataDir string, truncate bool) error
 	return nil
 }
 
-func (s *Store) loadOrInitializeHeader(truncate bool) error {
+func (s *Database) loadOrInitializeHeader(truncate bool) error {
 	if truncate {
 		initialMCH := uint64(0)
 		if s.options.MinimumHeight > 1 {
@@ -125,25 +125,25 @@ func (s *Store) loadOrInitializeHeader(truncate bool) error {
 	return nil
 }
 
-// NewStore creates or opens a block store.
+// New creates a block database.
 // Parameters:
 //   - indexDir: Directory for the index file
 //   - dataDir: Directory for the data file(s)
 //   - syncToDisk: If true, forces fsync after writes for guaranteed recoverability
 //   - truncate: If true, truncates existing store files
-//   - opts: Optional configuration parameters
+//   - config: Optional configuration parameters
 //   - log: Logger instance for structured logging
-func NewStore(indexDir, dataDir string, syncToDisk bool, truncate bool, opts StoreOptions, log logging.Logger) (*Store, error) {
+func New(indexDir, dataDir string, syncToDisk bool, truncate bool, config DatabaseConfig, log logging.Logger) (*Database, error) {
 	if indexDir == "" || dataDir == "" {
 		return nil, fmt.Errorf("both indexDir and dataDir must be provided")
 	}
 
-	if err := opts.Validate(); err != nil {
+	if err := config.Validate(); err != nil {
 		return nil, err
 	}
 
-	s := &Store{
-		options:    opts,
+	s := &Database{
+		options:    config,
 		syncToDisk: syncToDisk,
 		log:        log,
 	}
@@ -166,7 +166,7 @@ func NewStore(indexDir, dataDir string, syncToDisk bool, truncate bool, opts Sto
 	return s, nil
 }
 
-func (s *Store) closeFiles() {
+func (s *Database) closeFiles() {
 	if s.indexFile != nil {
 		s.indexFile.Close()
 	}
@@ -176,22 +176,22 @@ func (s *Store) closeFiles() {
 }
 
 // MaxContiguousHeight returns the highest block height known to be contiguously stored.
-func (s *Store) MaxContiguousHeight() BlockHeight {
+func (s *Database) MaxContiguousHeight() BlockHeight {
 	return s.maxContiguousHeight.Load()
 }
 
 // MinHeight returns the minimum block height configured for this store.
-func (s *Store) MinHeight() uint64 {
+func (s *Database) MinHeight() uint64 {
 	return s.header.MinBlockHeight
 }
 
-func (s *Store) MaxBlockHeight() BlockHeight {
+func (s *Database) MaxBlockHeight() BlockHeight {
 	return s.maxBlockHeight.Load()
 }
 
 // Close flushes pending writes and closes the store files.
 // It is safe to call Close multiple times.
-func (s *Store) Close() error {
+func (s *Database) Close() error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 

x/blockdb/store.go renamed to x/blockdb/database.go

@@ -8,7 +8,7 @@ var (
 	ErrBlockEmpty                = fmt.Errorf("blockdb: block is empty")
 	ErrBlockSizeMismatch         = fmt.Errorf("blockdb: block size in index file does not match data header")
 	ErrChecksumMismatch          = fmt.Errorf("blockdb: checksum mismatch")
-	ErrStoreClosed               = fmt.Errorf("blockdb: store is closed")
+	ErrDatabaseClosed            = fmt.Errorf("blockdb: database is closed")
 	ErrInvalidCheckpointInterval = fmt.Errorf("blockdb: invalid checkpoint interval")
 	ErrCorrupted                 = fmt.Errorf("blockdb: unrecoverable corruption detected")
 	ErrBlockTooLarge             = fmt.Errorf("blockdb: block size exceeds maximum allowed size of %d bytes", MaxBlockDataSize)

x/blockdb/errors.go

@@ -91,7 +91,7 @@ func (h *IndexFileHeader) UnmarshalBinary(data []byte) error {
 	return nil
 }
 
-func (s *Store) indexEntryOffset(height BlockHeight) (uint64, error) {
+func (s *Database) indexEntryOffset(height BlockHeight) (uint64, error) {
 	if height < s.header.MinBlockHeight {
 		return 0, fmt.Errorf("%w: height %d is less than minimum block height %d", ErrInvalidBlockHeight, height, s.header.MinBlockHeight)
 	}
@@ -107,7 +107,7 @@ func (s *Store) indexEntryOffset(height BlockHeight) (uint64, error) {
 	return finalOffset, nil
 }
 
-func (s *Store) readIndexEntry(height BlockHeight) (IndexEntry, error) {
+func (s *Database) readIndexEntry(height BlockHeight) (IndexEntry, error) {
 	offset, err := s.indexEntryOffset(height)
 	if err != nil {
 		return IndexEntry{}, err
@@ -128,7 +128,7 @@ func (s *Store) readIndexEntry(height BlockHeight) (IndexEntry, error) {
 	return entry, nil
 }
 
-func (s *Store) writeIndexEntryAt(indexFileOffset, dataFileBlockOffset, blockDataLen uint64) error {
+func (s *Database) writeIndexEntryAt(indexFileOffset, dataFileBlockOffset, blockDataLen uint64) error {
 	indexEntry := IndexEntry{
 		Offset: dataFileBlockOffset,
 		Size:   blockDataLen,
@@ -145,7 +145,7 @@ func (s *Store) writeIndexEntryAt(indexFileOffset, dataFileBlockOffset, blockDat
 	return nil
 }
 
-func (s *Store) persistIndexHeader(syncToDisk bool) error {
+func (s *Database) persistIndexHeader(syncToDisk bool) error {
 	// Why fsync indexFile before writing its header?
 	// To prevent a critical inconsistency: the header must not describe a state
 	// more advanced than what's durably stored in the index entries.

x/blockdb/index.go

@@ -15,7 +15,7 @@ const (
 // recover attempts to restore the store to a consistent state by scanning the data file
 // for blocks that may not be correctly indexed, usually after an unclean shutdown.
 // It reconciles the data file with the index file header and entries.
-func (s *Store) recover() error {
+func (s *Database) recover() error {
 	dataFileInfo, err := s.dataFile.Stat()
 	if err != nil {
 		return fmt.Errorf("failed to get data file stats for recovery: %w", err)
@@ -94,7 +94,7 @@ func (s *Store) recover() error {
 
 // recoverBlockAtOffset attempts to read, validate, and index a block at the given offset.
 // Returns the blockHeader and an error if the block is invalid or incomplete.
-func (s *Store) recoverBlockAtOffset(offset, dataFileActualSize uint64) (blockHeader, error) {
+func (s *Database) recoverBlockAtOffset(offset, dataFileActualSize uint64) (blockHeader, error) {
 	var bh blockHeader
 	if dataFileActualSize-offset < sizeOfBlockHeader {
 		return bh, fmt.Errorf("not enough data for block header at offset %d", offset)
@@ -143,7 +143,7 @@ func (s *Store) recoverBlockAtOffset(offset, dataFileActualSize uint64) (blockHe
 
 // updateMaxContiguousHeightOnRecovery extends the max contiguous height from the value in the header,
 // incrementing as long as contiguous blocks exist.
-func (s *Store) updateMaxContiguousHeightOnRecovery() {
+func (s *Database) updateMaxContiguousHeightOnRecovery() {
 	currentMCH := s.header.MaxContiguousBlockHeight
 	highestKnown := s.maxBlockHeight.Load()