nimbus-eth1/nimbus/db/core_db/README.md

Core database replacement wrapper object
========================================
This wrapper replaces the *TrieDatabaseRef* and its derivatives by the new
object *CoreDbRef*.

Relations to current *TrieDatabaseRef* implementation
-----------------------------------------------------
Here are some incomplete translations for objects and constructors.

### Object types:

| **Legacy notation**         | **CoreDbRef based replacement**       |
|:----------------------------|:--------------------------------------|
|                             |                                       |
| ChainDB                     | (don't use/avoid)                     |
| ChainDbRef                  | CoreDbRef                             |
| TrieDatabaseRef             | CoreDbKvtRef                          |
| HexaryTrie                  | CoreDbMptRef                          |
| SecureHexaryTrie            | CoreDbPhkRef                          |
| DbTransaction               | CoreDbTxRef                           |
| TransactionID               | CoreDbTxID                            |


### Constructors:

| **Legacy notation**         | **CoreDbRef based replacement**       |
|:----------------------------|:--------------------------------------|
|                             |                                       |
| trieDB newChainDB("..")     | newCoreDbRef(LegacyDbPersistent,"..") |
| newMemoryDB()               | newCoreDbRef(LegacyDbMemory)          |
| --                          |                                       |
| initHexaryTrie(db,..)       | db.mpt(..)      (no pruning)          |
|                             | db.mptPrune(..) (w/pruning true/false)|
| --                          |                                       |
| initSecureHexaryTrie(db,..) | db.phk(..)      (no pruning)          |
|                             | db.phkPrune(..) (w/pruning true/false)|
| --                          |                                       |
| newCaptureDB(db,memDB)      | db.capture()    (see below)           |


Usage of the replacement wrapper
--------------------------------

### Objects pedigree:

        CoreDbRef                        -- base descriptor
         | | |
         | | +--- CoreDbCtxRef           -- MPT context descriptor
         | |        | |
         | |        | +-- CoreDbMptRef   -- hexary trie instance
         | |        | |    :                    :
         | |        | +-- CoreDbMptRef   -- hexary trie instance
         | |        |
         | |        |
         | |        +---- CoreDbPhkRef   -- pre-hashed key hexary trie instance
         | |        |      :                    :
         | |        +---- CoreDbPhkRef   -- pre-hashed key hexary trie instance
         | |
         | |
         | +------ CoreDbKvtRef          -- single static key-value table
         |
         |
         +-------- CoreDbCaptRef         -- tracer support descriptor

### Instantiating legacy standard database object descriptors works as follows:

        let
          db = newCoreDbRef(..)           # new base descriptor
          mpt = db.mpt(..)                # hexary trie/Merkle Patricia Tree
          phk = db.phk(..)                # pre-hashed key hexary trie/MPT
          kvt = db.kvt                    # key-value table

### Tracer support setup by hiding the current *CoreDbRef* behind a replacement:

        let
          capture = db.capture()
          db = capture.recorder           # use the recorder in place of db
        ...

        for key,value in capture.recorder.kvt:
         ...                              # process recorded data