Immutable on-disk database of binary blobs

Internal format

The API of the ImmutableDB uses SlotNo to indicate a location in the chain/immutable database. To distinguish EBBs from regular blocks, the hash is used (together they form a RealPoint). The contents of the database are not stored in one big file that is appended to in eternity, but a separate file is created for each ChunkNo.

Within each ChunkNo, the entries are numbered by RelativeSlots. Each SlotNo can be converted to a combination of an ChunkNo and a RelativeSlot (= ChunkSlot) and vice versa. This conversion depends on the size of the chunks: ChunkSize. This size may not be the same for each chunk. When opening the database, the user must give a ChunkInfo that will be used to find out the size of each chunk.

For example:

Chunks:         <──────── 0 ────────> <────── 1 ──────>
chunk size:               4                   3
                ┌───┬───┬───┬───┬───┐ ┌───┬───┬───┬───┐
                │   │   │   │   │   │ │   │   │   │   │
                └───┴───┴───┴───┴───┘ └───┴───┴───┴───┘
'RelativeSlot':   0   1   2   3   4     0   1   2   3
'SlotNo':        EBB  0   1   2   3    EBB  4   5   6

Not all chunks can contain EBBs; see ChunkInfo for details.

Errors

Whenever an ImmutableDBError is thrown during an operation, e.g., appendBlock, the database will be automatically closed because we can not guarantee a consistent state in the face of file system errors.

Opening the database

The database can be closed and opened again. In case the database was closed because of an unexpected error. When the database is opened again, invalid data will be truncated from the database until a valid prefix is recovered.

Concurrency

The same database should not be opened multiple times concurrently. This is ensured by the file lock of the ChainDB.

The database can have multiple readers, but should only have one writer.

Layout on disk

The database is structured on disk as follows:

/
  00000.chunk
  00000.primary
  00000.secondary
  ..
  00008.chunk
  00008.primary
  00008.secondary

For each chunk, there are three files on disk:

• A "chunk file" that stores the actual blocks. But nothing more, so nothing is stored for empty slots.
• A "secondary index file" that stores information about each block: its hash, the slot number or epoch number in case of an EBB, a checksum of the block, the offset of the block in the chunk file, and more. This index is sparse to save space.
• A "primary index file" that maps slots to offsets in the secondary index file.