nimbus-eth1/nimbus/db
Jacek Sieka 293ce28e4d
remove geth_db (#2189)
doesn't look like it's used
2024-05-16 22:00:20 +07:00
..
aristo Kvt remodel tx and forked descriptors (#2168) 2024-05-07 19:59:27 +00:00
core_db Introduce wrapper type for EIP-4844 transactions (#2177) 2024-05-15 10:07:59 +07:00
kvt Kvt remodel tx and forked descriptors (#2168) 2024-05-07 19:59:27 +00:00
ledger remove geth_db (#2189) 2024-05-16 22:00:20 +07:00
notused Add check copyright year linter to CI 2023-11-01 10:41:20 +07:00
state_db evm: Reject contract creation if the storage is non-empty(EIP-7610) 2024-05-07 09:19:59 +07:00
.gitignore Database architecture diagram & module overview (#2065) 2024-03-08 18:42:46 +00:00
README.md Database architecture diagram & module overview (#2065) 2024-03-08 18:42:46 +00:00
access_list.nim Implement RPC method eth_getAccessList (#2091) 2024-03-21 18:24:32 +07:00
aristo.nim Coredb use stackable api for aristo backend (#2060) 2024-02-29 21:10:24 +00:00
core_db.nim Provide public default db symbol (#2050) 2024-02-23 09:17:24 +00:00
distinct_tries.nim Misc updates for full sync (#2140) 2024-04-19 18:37:27 +00:00
incomplete_db.nim remove geth_db (#2189) 2024-05-16 22:00:20 +07:00
kvstore_rocksdb.nim Generalise prune mode option 4 different db models (#2139) 2024-04-17 18:09:55 +00:00
kvt.nim Coredb use stackable api for aristo backend (#2060) 2024-02-29 21:10:24 +00:00
ledger.nim Core db update storage root management for sub tries (#1964) 2024-01-11 19:11:38 +00:00
state_db.nim Rename hasCodeOrNonce to contractCollision 2024-04-16 09:31:10 +07:00
storage_types.nim Core db+aristo update recovery journal management (#2156) 2024-04-29 20:17:17 +00:00
transient_storage.nim implement EIP-1153: Transient storage 2023-06-23 14:04:36 +07:00
trie_get_branch.nim Implementation of Nimbus eth_getProof RPC Endpoint. (#1960) 2024-01-09 10:05:52 +08:00
values_from_bytes.nim Add check copyright year linter to CI 2023-11-01 10:41:20 +07:00

README.md

Nimbus-eth1 -- Ethereum execution layer database architecture

Last update: 2024-03-08

The following diagram gives a simplified view how components relate with regards to the data storage management.

An arrow between components a and b (as in a->b) is meant to be read as a relies directly on b, or a is served by b. For classifying the functional type of a component in the below diagram, the abstraction type is enclosed in brackets after the name of a component.

  • (application)
    This is a group of software modules at the top level of the hierarchy. In the diagram below, the EVM is used as an example. Another application might be the RPC service.

  • (API)
    The API classification is used for a thin software layer hiding a set of different drivers where only one driver is active for the same API instance. It servers as sort of a logical switch.

  • (concentrator)
    The concentrator merges several sub-module instances and provides their collected services as a single unified instance. There is not much additional logic implemented besides what the sub-modules provide.

  • (driver)
    The driver instances are sort of the lower layer workhorses. The implement logic for solving a particular problem, providing a typically well defined service, etc.

  • (engine)
    This is a bottom level driver in the below diagram.

                                          +-------------------+
                                          | EVM (application) |
                                          +-------------------+
                                               |          |
                                               v          |
                            +-------------------------+   |
                            | State DB (concentrator) |   |
                            +-------------------------+   |
                                |           |       |     |
                                v           |       |     |
       +----------------------------+       |       |     |
       |       Ledger (API)         |       |       |     |
       +----------------------------+       |       |     |
                    |      |                |       |     |
                    v      v                |       |     |
       +--------------+  +--------------+   |       |     |
       | legacy cache |  | ledger cache |   |       |     |
       |   (driver)   |  |   (driver)   |   |       |     |
       +--------------+  +--------------+   |       |     |
                    |      |                v       |     |
                    |      |   +----------------+   |     |
                    |      |   |   Common       |   |     |
                    |      |   | (concentrator) |   |     |
                    |      |   +----------------+   |     |
                    |      |         |              |     |
                    v      v         v              v     v
       +---------------------------------------------------------------------+
       |               Core DB (API)                                         |
       +---------------------------------------------------------------------+
                       |                  |
                       v                  v
       +--------------------------+   +--------------------------------------+
       | legacy DB (concentrator) |   |   Aristo DB (driver,concentrator)    |
       +--------------------------+   +--------------------------------------+
             |                 |                |          |
             v                 |                v          v
       +--------------------+  |     +--------------+  +---------------------+
       | Hexary DB (driver) |  |     | Kvt (driver) |  | Aristo MPT (driver) |
       +--------------------+  |     +--------------+  +---------------------+
             |                 |                |          |
             v                 v                |          |
       +--------------------------+             |          |
       | Key-value table (driver) |             |          |
       +--------------------------+             |          |
                    |                           |          |
                    v                           v          v
       +---------------------------------------------------------------------+
       |                Rocks DB (engine)                                    |
       +---------------------------------------------------------------------+
    

Here is a list of path references for the components with some explanation. The sources for the components are not always complete but indicate the main locations where to start looking at.

  • Aristo DB (driver)

    • Sources:
      ./nimbus/db/core_db/backend/aristo_*

    • Synopsis:
      Combines both, the Kvt and the Aristo driver sub-modules providing an interface similar to the legacy DB (concentrator) module.

  • Aristo MPT (driver)

    • Sources:
      ./nimbus/db/aristo*

    • Synopsis:
      Revamped implementation of a hexary Merkle Patricia Tree.

  • Common (concentrator)

    • Sources:
      ./nimbus/common*

    • Synopsis:
      Collected information for running block chain execution layer applications.

  • Core DB (API)

    • Sources:
      ./nimbus/db/core_db*

    • Synopsis:
      Database abstraction layer. Unless for legacy applications, there should be no need to reach out to the layers below.

  • EVM (application)

    • Sources:
      ./nimbus/core/executor/* ./nimbus/evm/*

    • Synopsis:
      An implementation of the Ethereum Virtual Machine.

  • Hexary DB (driver)

  • Key-value table (driver)

    • Sources:
      ./vendor/nim-eth/eth/trie/db.nim

    • Synopsis:
      Key value table interface to be used directly for key-value storage or by the Hexary DB (driver) module for storage. Some magic is applied in order to treat hexary data accordingly (based on key length.)

  • Kvt (driver)

  • Ledger (API)

  • ledger cache (driver)

    • Sources:
      ./nimbus/db/ledger/accounts_ledger.nim
      ./nimbus/db/ledger/backend/accounts_ledger*
      ./nimbus/db/ledger/distinct_ledgers.nim

    • Synopsis:
      Management of accounts and storage data. This is a re-write of the legacy DB (driver) which is supposed to work with all Core DB (API) backends.

  • legacy cache (driver)

    • Sources:
      ./nimbus/db/distinct_tries.nim
      ./nimbus/db/ledger/accounts_cache.nim
      ./nimbus/db/ledger/backend/accounts_cache*

    • Synopsis:
      Management of accounts and storage data. It works only for the legacy driver of the Core DB (API) backend.

  • legacy DB (concentrator)

  • Rocks DB (engine)

    • Sources:
      ./vendor/nim-rocksdb/*

    • Synopsis:
      Persistent storage engine.

  • State DB (concentrator)

    • Sources:
      ./nimbus/evm/state.nim
      ./nimbus/evm/types.nim

    • Synopsis:
      Integrated collection of modules and methods relevant for the EVM.