feat(internal/client/db) Introduce api.Backend interface and db.Backend implementation

[timwu20]

Changes

api.Backend

This is the client backend interface where trie state can be retrieved for a given block hash. State pruning achieved using StateDB, and historical block pruning is performed by blockchainDB.

api.AuxStore

This is an interface that provides access to an auxiliary database. This database is not fork-aware. This interface is embedded into api.Backend

Backend.BeginOperation

Begins a new block insertion transaction. What is returned is something that implements api.BlockImportOperation.

Backend.BeginStateOperation

Notes the BlockImportOperation to contain a state transition.

Backend.CommitOperation

Commits a BlockImportOperation into the backend.

Backend.FinalizeBlock

Finalizes a block for a given hash. Takes an optional justification to be stored.

Backend.PinBlock and Backend.UnpinBlock

This will pin a block into memory to avoid it from being pruned during state pruning or block pruning. UnpinBlock will allow the block to be pruned from memory.

Backend.StateAt

Retrieve the state at a given block. Returns a statemachine.Backend implementation which will allow you to query state, but not mutate the state.

Backend.GetImportLock

Returns a pointer to the shared sync.RWMutex for the backend. NOTE: the backend doesn't actually acquire the lock by itself, this is supposed to be used by the callers of api.Backend to handle concurrent block imports.

api.BlockImportOperation

An implementation of this interface is returned you by calling api.Backend.BeginOperation. This keeps track of the inserted block data and state mutations that will be commited into the backend using api.Backend.CommitOperation.

BlockImportOperation.State

Returns the pending state for this block. Can be nil if no state is associated.

BlockImportOperation.SetBlockData

Sets block data to the operation. The header, body, indexed body, and justifications can be set. The state of the block can be set as Normal, Best and Final.

BlockImportOperation.SetGenesisState

Accepts a storage.Storage which holds all the top trie and child trie changes. Accepts a commit boolean which will determine whether or not the changes will be commited to the underlying database.

BlockImportOperation.UpdateStorage

Updates the top level trie as well as child tries.

BlockImportOperation.InsertAux

Insert/update auxiliary data.

BlockImportOperation.MarkFinalized

Marks the incoming block as finalized. Accepts an optional justification.

BlockImportOperation.MarkHead

Marks the incoming block as the new head. Will override the backend best block rule.

db.Backend

This is the default implementation of api.Backend. Calling Backend.BeginOperation will return a db.BlockImportOperation which implements api.BlockImportOperation.

db.NewBackend

This is the constructor for db.Backend. It accepts two parameters:

• dbConfig which is an instance of DatabaseSettings
• canonicalizationDelay which represents the delay in number of blocks that canonicalization/finalization will enact on the backend.

DatabaseSettings

This type represents the configurable settings for db.Backend. The maximum size of the trie cache in bytes can be set. statedb.PruningMode can be set to alter how the trie is pruned. BlocksPruning can be set to KeepAll, KeepFinalized or KeepSome which will constrain the amount of blocks to a certain number of finalized blocks.

db.Backend dependencies

This is a quick overview on the introduced dependencies for db.Backend.

offchain.LocalStorage

Used for offchain storage. Will store in the underlying DB.

dbGenesisStorage

A private type to represent the genesis state when we don't want to commit the state to the underlying database.

db.BlockImportOperation

This is the implementation of api.BLockImportOperation which is utilized by db.Backend. The introduced dependencies are outlined below.

db.refTrackingState

This is used within db.BlockImportOperation as a reference to the trie backend as well as the underlying database and statedb.StateDB. It stores an optional parent hash.

db.pendingBlock

A private type to represent a pending block.

Other Notable Additions

blockchain.TreeTroute

A type with an associated NewTreeRoute constructor that represents a block tree route.

kvdb.KeyValueDB

An interface for a database that deal with "column families" which are distinct tables within a database. This is essentially the interface that a key value database must conform to.

memorykvdb.MemoryKVDB

An implementation of kvdb.KeyValueDB completely in memory. Used only in tests.

database.DBAdapter

A helper type that wraps a kvdb.KeyValueDB that implements database.Database interface. Supports the reference counting required for database.Database by adding counter records to the underlying database.

saturating package

This package introduces Sub and Into which is used for saturating operations for unsigned integers. This is to ensure we don't overflow minimum and maximum values when casting between unsigned integer types.

Tests

go test -tags integration github.com/ChainSafe/gossamer

Issues

closes #3900

[dimartiro]

overall looks good but I have some suggestions that want to discuss.
Apart from that I'd suggest to follow the godoc conventions when documenting exported struct and functions, I noticed you are following it but not always