Skip to content

Glossary

Jump to bottom
Piper Merriam edited this page Jan 30, 2021 · 1 revision

The Eth1x Glossary

Data

Header

The Header object used by the Ethereum protocol

Block

The collection of:

Block Body

The collection of Transactions and Uncles for a given block.

Transaction

The Transaction object used by the Ethereum protocol

Transaction Construction

The process of creating a fully signed transaction.

  • The Account nonce must be known.
  • Typically involves using eth_estimateGas to determine the gas value for the transaction.
  • Requires a private key to sign.

Uncle

The Header for a block that was uncled

Chain History

Header Chain

The set of all historical block headers.

  • ~11 million as of 2021/01/29
  • ~5GB of storage as of 2021/01/29
  • Needed to verify most other chain data.
  • Header Accumulator would allow proving historical header inclusion into the canonical chain.

Block Body History

The set of all transactions and uncles for historical blocks.

  • ~11 million as of 2021/01/29
  • ~120GB of storage as of 2021/01/29

Receipt History

The set of all receipts generated by historical transactions.

  • ~1 billion total receipts as of 2021/01/29
  • ~60GB of storage as of 2021/01/29

State

The set of all accounts and contract storage

Account

The objects that are part of the main state trie represented by the Header.state_root

  • Fields: balance/nonce/state_root/code_hash

Contract Storage

The individual storage denoted by Account.state_root for each account.

  • All data is keyed to an integer slot number in the range 0 - 2**256-1

Contract Code

Contract code is only referenced by the Account.code_hash and is not explicitely part of the state.

Archive State

Refers to the combined set of all historical states. See Archive Node

Recent State

Refers to only the state that is part of a recent state root.

  • Recent tends to be on the order of 128-256 blocks.

Maintaining this data requires some form of garbage collection to clean up state that is no longer part of a recent state root.

Cold State

Refers to pieces of the state that have not been touched (read or modified) for some extended amount of time.

Database Layouts

Naive Database Layout

Implementation of the state which store all of the data by individual trie nodes addressed by the node hash.

  • Results in poor performance and high disk IO overhead.
  • Relatively simple to understand and implement
  • Garbage collection under this scheme is more complex

Flat Database Layout

Implementation of the state with stores all of the data by trie path, somewhat akin to a key/value store.

  • More performant and reduces disk IO.
  • More complex to understand and implement.

Witnesses

State data that is in a format which can be verified.

Block Witness

A Witness that provides all of the data needed to perform Block Execution

Transaction Witness

A Witness that provides all of the data needed to perform EVM Execution for a specific transaction.

Node Types

Full Node

A node which:

Archive Node

The same as a Full Node except that it store the full Archive State. Typically requires doing a Full Sync.

LES Light Node

A client that connects to the LES DevP2P Protocol in order to follow the chain and expose the JSON-RPC API.

Clients depend on connecting to at least one LES Server to serve requests for data.

Stateless Node

A planned type of client that could be built if Block-Witnesses were available.

  • Client does not need the State to execute blocks as they are executed statelessly, using witnesses.

TODO: more about what is needed for other capabailities

Ultra Light Node

Terminology to try and distinguish between current light nodes and a new type of light node - Piper

A node which only exposes the JSON-RPC API

ETH DevP2P Protocol

P2P protocol on the DevP2P network that serves as the foundation for all mainnet clients

Nodes that are apart of this network are required to:

LES DevP2P Protocol

P2P protocol on the DevP2P network that serves as the foundation for light clients.

LES Server

A node in the LES network that serves data to LES Clients.

Being a server on this network requires:

LES Client

A node on the LES network that requests data from LES Servers

Gossip

Transaction Gossip

Block Gossip

Historical Data Retrieval

  • Retrieval of headers
    • by hash
    • by number
    • in batches, either sequential or with consistently spaced gaps
  • Retrieval of block bodies
    • Data needs to be verified against Header.transactions_root and Header.uncles_root
  • Retrieval of receipts
    • Retrieved in batches by block
    • Data needs to be verified against Header.receipts_root

State Retrieval

  • Retrieval of individual trie nodes by their hash
    • Likely to be removed in a future iteration of the protocol as this retrieval mechanism is not condusive to flat database layout

Following the Chain

Transaction Validation

Validation of transactions involves:

  • ability to perform the ecrecover operation to determine sender
  • checking that the nonce is the next nonce for the sending account
  • checking that the account balance is sufficient to pay for intrinsic gas
    • requires knowing EVM rules for computing intrinsic gas value

Block Validation

Validation of a block can involve any of the following things:

  • checking the Proof-of-work seal
    • Computationaly expensive
  • checking the computed total difficulty against other competing blocks at the same height
  • execution of the transactions to verify correctness of the Header.state_root

Header Accumulator

An efficient mechanism for being able to provide concise proofs about historical header inclusion into the canonical chain based on https://ethresear.ch/t/double-batched-merkle-log-accumulator/571

Canonical Indexes

Canonical Block Index

Maps block numbers to the canonical block hash at that height

  • Needs to be built from the Header chain.
  • 61MB per 1 million blocks
    • 64 bytes per entry
      • 32 bytes for block number
        • Can be reduced with more efficient variable length encoding
      • 32 bytes for block hash
  • ~600MB total size as of 2021/01/29
  • Only provable by verifying hash against known canonical block hash at that height.
  • Can be more efficiently proven with addition of Header accumulator to the protocol

Canonical Transaction Index

Maps transaction hashes to the canonical block hash and transaction index within that block.

  • Needs to be built from the historical block bodies
  • ~1 billion total historical transactions as of 2021/01/29
  • 70 bytes per entry
    • 32 bytes for transaction hash
    • 32 bytes for canonical block hash
    • 4 bytes for transaction index
      • Can be reduced slightly with more efficient variable length encoding
  • 65GB as of 2021/01/29
  • Can be proven with merkle proof against Header.transactions_root

Syncing

History Syncing

Header Syncing

The process that a client uses to catch up to the head of the chain. There are a few approaches that can be used depending on the security profile.

  • Full verification
    • Downloading the full chain of headers
  • Checkpointing
    • Using a trusted hash of a more recent header and syncing from there.
  • Following the HEAD
    • A reasonably high degree of confidence can be achieved by simply following the latest headers. The longer this chain grows, the more effort an attacker would need to have invested to fake the chain.

Currently, the full historical chain of headers is required to verify any other parts of the historical data. The Header Accumulator would improve this situation, allowing a client to checkpoint to the tip of the chain, but still be capable of verifying historical data.

Block Syncing

The process that a client uses to pull historical transactions and uncles.

  • Verifying this data requires access to the Header Chain to check the data against the Header.transactions_root and Header.uncles_root

Receipt Syncing

Clients that do not Full Sync tend to need to acquire the historical receipts by fetching them over the ETH DevP2P Protocol.

  • Verifying this data requires access to the Header Chain to check the data against the Header.receipts_root

State Syncing

A mechanism for nodes to pull a full copy of the Recent State.

Full Sync

Syncing by downloading all historical blocks and executing them in order.

Fast Sync

Syncing by downloading the chain history and a recent copy of the state.

  • Operates on the security assumption that the state roots calculated by historical blocks was done correctly.
  • requires History Syncing
  • Places a heavy load on nodes serving the data
  • Difficult to serve from a Flat Database Layout

Snap Sync

Syncing by downloading the chain history and a recent copy of the state.

  • Operates on the security assumption that the state roots calculated by historical blocks was done correctly.
  • requires History Syncing
  • Better suited for Flat Database Layout
  • Uses orders of magnitute less bandwidth, disk IO, time.

Stateless Sync

This term is not widely used so the definition may adjust over time

Unlike the other State Syncing approaches, this approach does not actually result in obtaining a full copy of the state. This approach could be used on its own to verify blocks without needing a local copy of the state, or in conjunction with one of the other sync approaches to allow immediate verification of blocks until the full state is available locally.

Beam Sync

Beam sync is effectively Stateless Sync but without having the network provide Block Witnesses. Instead, the client fetching state on demand as it is needed.

Mining

Access List

The list of accounts and contract storage locations touched during some form of EVM Execution

State Access Patterns

Static State Access (SSA)

A property of some EVM Execution where a caller can accurately predict what state would be touched.

Dynamic State Access (DSA)

A property of some EVM Execution where a caller cannot accurately predict what state would be touched.

Block Execution

  • requires EVM Execution
  • the process of executing all of the transactions in a given
  • Computationaly expensive

EVM Execution

Account Management

Keyfile

A encrypted storage format for private keys

Decryption tends to rely on access to cryptographic primatives like keccak, scrypt, pbkdf2, or ECC/BLS12-381.

On Demand State Retrieval

The ability retrieve any element from the State from the network.

GetNodeData

The ETH DevP2P Protocol exposes the message pair GetNodeData/NodeData which allows for retrieval of arbitrary state. This message is likely to be deprecated.

DHT based State Network

An idea for how we could distribute the state among across all of the nodes in a DHT and make it discoverable and retrievable on demand.

JSON-RPC

eth_protocolVersion

  • Meta information to the DevP2P Network.
  • Easy to stub/fake for clients that don't implement this functionality

eth_syncing

  • Meta information about the syncing status of the node.
  • Easy to stub/fake for clients that don't implement this functionality

eth_coinbase

  • Denotes the default address that will be used by the client
  • Easy to stub/fake for clients that don't implement this functionality
  • Only relevant for clients that implement Account Management

eth_mining

  • Meta information about the mining status of the client
  • Only relevant for clients that mine
  • Easy to stub/fake for clients that don't implement this functionality

eth_hashrate

  • Meta information about mining
  • Only relevant for clients that mine
  • Easy to stub/fake for clients that don't implement this functionality

eth_gasPrice

  • Meta information about what the client thinks the gas price is
  • Easy to stub/fake for clients that don't implement this functionality

Picking an appropriate gas price is a context dependent operation with no global strategy that can be applied to all use cases.

eth_accounts

  • Lists all of the account addresses managed by the client.
  • Easy to stub/fake for clients that don't implement this functionality
  • Only relevant for clients that implement Account Management

eth_blockNumber

Some ambiguity around whether transactions/receipts/state is available at this height, or whether this is simply a view over the accepted header chain.

eth_getBalance

  • Return the balance of the provided address in units of wei
  • Requires access to the Account State

eth_getStorageAt

  • Return the value at the given storage slot of the given account
  • Requires access to the Contract Storage

eth_getTransactionCount

  • Return the nonce of the provided address in units of wei
  • Requires access to the Account State

eth_getBlockTransactionCountByHash

eth_getBlockTransactionCountByNumber

eth_getUncleCountByBlockHash

eth_getUncleCountByBlockNumber

eth_getCode

eth_sign

  • Returns the signature for the provided data
  • Only relevant for clients that implement Account Management

eth_signTransaction

  • Sign the provided transaction and return the RLP encoded representation of the signed transaction.
  • Only relevant for clients that implement Account Management
  • Requires access to the Account State to determine transaction nonce.

eth_sendTransaction

eth_sendRawTransaction

eth_call

  • Executes the provided transaction against the latest state known by the client and returns the result
  • Requires EVM Execution

eth_estimateGas

eth_getBlockByHash

eth_getBlockByNumber

  • Return a representation of the Block denoted by the provided hash
  • Requires access to the Header Chain
  • Requires access to the Block Body History
  • Requires access to the [Canonical Block Index](#Canonical Block Index)

Calls to this endpoint can be mapped directly to an equivalent call to eth_getBlockByHash with access to the Canonical Block Index

eth_getTransactionByHash

  • Returns a representation of the Transaction denoted by the provided hash
  • Requires access to the Header Chain
  • Requires access to the Block Body History
  • Requires access to the [Canonical Transaction Index](#Canonical Transaction Index)

Calls to this endpoint can be mapped directly to an equivalent call to eth_getTransactionByBlockHashAndIndex with access to the Canonical Transaction Index

eth_getTransactionByBlockHashAndIndex

eth_getTransactionByBlockNumberAndIndex

Calls to this endpoint can be mapped directly to an equivalent call to eth_getTransactionByBlockHashAndIndex with access to the Canonical Block Index

eth_getTransactionReceipt

eth_getUncleByBlockHashAndIndex

eth_getUncleByBlockNumberAndIndex

Calls to this endpoint can be mapped directy to an equivalent call to eth_getUncleByBlockHashAndIndex with access to the Canonical Block Index

eth_newFilter

eth_uninstallFilter

eth_getFilterChanges

eth_getFilterLogs

eth_getLogs

Clone this wiki locally