db_walkthrough.MD

This document attempts to explain how Erigon organises its persistent data in its database and how this organisation is different from go-ethereum, the project from which it is derived. We start from a very simple genesis block and then apply one block containing an ETH transfer. For each step, we show visualisations produced by the code available in Erigon and code added to a fork of go-ethereum.

Genesis in Erigon

For the genesis block, we generate 3 different private keys and construct Ethereum addresses from them. Then, we endow one of the accounts with 9 ETH, and two others with 0.2 and 0.3 ETH, respectively. This is how the initial state trie looks:

In this and other illustrations, the colored boxes correspond to hexadecimal digits (a.k.a. nibbles), with values 0..f. Here is the palette:

First thing to note about the illustration of the initial state trie is that the leaves correspond to our accounts with their ETH endowments. Account nonces, in our case all 0s, are also shown. If you count the number of coloured boxes, from top to bottom, up to any of the account leaves you will get 64. Since each nibble occupies half a byte, that makes each "key" in the state trie 32 bytes long. However, account addresses are only 20 bytes long. The reason we get 32 and not 20 is that all the keys (in our case account addresses) are processed by the Keccak256 hash function (which has 32 byte output) before they are inserted into the trie. If we wanted to see what the corresponding account addresses were, we will have to look into the database. Here is what Erigon would persist after generating such a genesis block:

The Erigon database is a key-value store organised in tables (also commonly referred to as "buckets"). This is the list of the main tables in the database:

• Headers
• Block Bodies
• Header Numbers
• Receipts
• PlainState
• History Of Accounts
• Change Sets
• HashedState
• IntermediateTrieHashes
• Tx Senders

Table "Headers"

This table stores information about block headers. For each block there are three types of block header records with the following (key, value) formats:

• FULL HEADER: contains the complete block header with all its information parameters
  • key : 8-byte big-endian block number + 32-byte block hash
  • value : the RLP-encoded block header structured as defined in the Ethereum Yellow Paper:
    • parent hash: 32-byte hash of the parent block
    • uncles hash: 32-byte hash of the uncle blocks
    • coinbase: 20-byte address beneficiary of mining reward
    • state root: 32-byte root hash of the state trie
    • transactions root: 32-byte root hash of the trie structure made up of the block transactions
    • receipts root: 32-byte root hash of the trie structure made up of the transaction receipts
    • logs bloom: 256-byte Bloom filter composed from indexable information in each log entry from the transaction receipts
    • difficulty: 8-byte scalar value corresponding to the diffculty level of this block
    • block number: 8-byte scalar value equal to the number of ancestor blocks in the chain (aka block heigth)
    • gas limit: 8-byte scalar value equal to the current limit of gas expenditure per block
    • gas used: 8-byte scalar value equal to the total gas used in transactions in this block
    • timestamp: 8-byte scalar value equal to the Unix epoch timestamp at the inception of this block
    • extra data: up to 32-byte array of additional relevant data for this block (at least for Eth-hash consensus engine, for Clique could be more)
    • mix_hash: 64-byte hash proving, combined with nonce, the computation amount spent in block mining
    • nonce: 8-byte value proving, combined with mix hash, the computation amount spent in block mining
• TOTAL DIFFICULTY HEADER: contains the total mining difficulty (TD) of the chain ending in such specific block
  • key : 8-byte big-endian block number + 32-byte block hash + 0x74 suffix (ASCII code for t character)
  • value : variable-length RLP-encoded total difficulty value: the cumulative difficulty value from first block to this one
• CANONICAL HEADER: contains the block hash
  • key: 8-byte big-endian block number + 0x6E suffix (ASCII code for n character)
  • value: 32-byte block hash

as shown in the following picture for the block 0 (from top to bottom the three types of records, key on the left and value on the right):

You can check that for the genesis block

• block number 0 is encoded as 0x0000000000000000 (see 8-byte zeros start of each key)
• block hash is 0x61eb...aba1
• logs bloom is 256-byte zeros (see the 8 white rows of all 32-byte 0s)
• total difficulty is 0x80, which is RLP encoding of value 0

Table "Block Bodies"

The keys in this table are concatenations of 8-byte encoding of the block number and 32-byte block hash. The values are RLP-encoded list of 2 structures: