DOCSEARCHbyAlgolia
Submit Docs

Nimbus Eth2 Documentation

repository·stable·Indexed 20 days ago

https://github.com/status-im/nimbus-eth2

A highly efficient Ethereum consensus layer (Beacon Chain) client implementation optimized for resource-constrained environments like Raspberry Pis and high-performance servers. Documentation covers consensus object pools, LMD-GHOST fork choice implementation, gossip processing and validation, P2P networking, block syncing workflows, validator operations (keystore, slashing protection, and duties), and the NBC Audit 2020 security evaluations.

Tokens
208.2K
Snippets
351
Records
561
Agent score
70%

What's inside Nimbus Eth2

  1. Overview of Validator modules in Nimbus Eth2

    stable
    The beacon_chain/validators directory contains the core logic for Beacon Chain Validator operations. It manages the lifecycle and safety of validators through several specialized modules. These modules are used by the primary validator binaries (nimbus_validator_client and nimbus_signing_process) to handle sensitive operations like key management and duty execution.

  2. Overview of Nimbus Eth2 Networking modules

    stable

    The networking modules in Nimbus Eth2 are responsible for managing the Eth2 P2P network. Their primary responsibilities include:

    1. Configuration: Setting up the Eth2 P2P network parameters.
    2. Peer Management: Discovering, connecting to, and maintaining the quality of Eth2 peers.

    Data Flow: Once data is received via the networking layer, it is handed over to the ../gossip_processing modules for validation.

  3. Overview of Nimbus Eth2 components

    stable

    Nimbus is a lightweight and secure Ethereum consensus client designed to run on a wide range of hardware, from mobile devices and Raspberry Pis to high-performance servers.

    The project provides three primary consensus protocol implementations:

    1. Beacon Node: A full node implementation that includes an integrated validator client, slashing protection, and doppelganger detection.
    2. Validator Client: A standalone client for managing validator duties, featuring support for sentry node setups.
    3. Consensus Light Client: A specialized client designed to allow an execution client to function without requiring a full beacon node.

    Note: An execution client (nimbus-eth1) is a separate project.

  4. Overview of the NBC Audit 2020

    stable

    The NBC Audit 2020 documentation outlines the security audit scope, tasks, and modules evaluated prior to the Nimbus mainnet launch. The audit was conducted in three phases across multiple repositories and involved three security vendors: Consensys Diligence, NCC, and Trail of Bits.

    Key audit categories include:

    • Network Core Audit: Covering wire encryption, discovery protocols (discv5), and gossipsub.
    • Validator Core Audit: Covering block/attestation signing, CLI, RPC API, account management, and slash-prevention.
    • ETH2 Specification Core Audit: Covering SSZ serialization, peer pool management, block synchronization, fork choice logic, reward processing, and state transition logic.

  5. Overview of ncli tools

    stable
    ncli is a suite of low-level debugging and interaction tools for the Nimbus Beacon Chain implementation. It is designed to help developers explore SSZ (Simple Serialize) data, perform state transitions, and compute hash tree roots. It is conceptually similar to zcli.

  6. Understand the ConsensusSpecPreset-mainnet test suite

    stable

    The ConsensusSpecPreset-mainnet documentation provides a reference for the test cases used to validate the Nimbus Eth2 implementation against the Ethereum Consensus Specification (EF) using the mainnet preset. These tests are categorized into functional groups such as Randomness, Rewards, Sanity Checks (Blocks), Epoch Processing (Builder payments, Effective balance updates), and various Fork operations (e.g., Altair).

    Test results are marked as [Valid] or [Invalid] to indicate whether the expected behavior (valid or invalid state transitions) was correctly identified by the client. A result of OK indicates the test passed successfully.

  7. Understand the Nimbus Beacon Chain (NBC) architecture and audit scope

    stable

    Nimbus Beacon Chain (NBC) is an Ethereum 2 client implementation. For developers or auditors, the project's surface area is divided into three primary domains:

    1. Network Core: Built on the libp2p framework. Key components include the Discovery Protocol (discv5), Publish/Subscribe protocols, Eth2 Request/Response protocols, SSZ (Simple Serialize) for (de)serialization and tree hashing, and wire encryption.
    2. ETH2 Specification Core: Implements the consensus logic including state transitions, signature verification, epoch finalization/justification, reward processing, Eth1 data processing, fork choice logic, block/attestation processing, and block synchronization.
    3. Validator Core and User Experience: Handles the operational side of being a validator, including block/attestation signing, slash-prevention mechanisms, the RPC API, account management/key storage, and the Command Line Interface (CLI).

  8. Understand Gossip Processing and Validation in Nimbus

    stable

    Gossip processing in Nimbus serves as the first line of defense for the Beacon Chain. It consists of modules designed to validate raw gossip data before it is either rebroadcast via libp2p or sent to consensus object pools.

    Validation is distinct from consensus verification. The gossip processing layer validates several types of consensus objects, including:

    • Blocks
    • Aggregated Attestations
    • Unaggregated Attestations
    • Voluntary Exits
    • Proposer Slashings
    • Attester Slashings

    Developers should note that these modules must be resilient to data bursts caused by malicious DoS attacks or periods of non-finality that generate high volumes of forks and attestations.

  9. Understand Nimbus Eth2 fork choice implementations

    stable

    Nimbus Eth2 implements fork choice rules as defined by the Ethereum consensus specifications. The implementation is designed to follow the LMD-GHOST (Latest Message Driven - Graveyard Observed Synthesis Tool) algorithm.

    For detailed technical specifications, refer to the following external resources:

  11. Understand the Nimbus Docker directory layout

    stable

    The docker/ directory is organized into three main components used for building and distributing Nimbus binaries:

    • dist/base_image/: Contains the base Docker images used to build distributable binaries. These are uploaded to Docker Hub to ensure official releases can be reproduced.
    • dist/: Contains Dockerfiles used to build local Docker images based on the base images. These are used specifically for generating distributable binaries and are not uploaded to Docker Hub.
    • dist/binaries/: Contains the final Docker images intended for end-users. These images consist of official Debian images with the Nimbus distributable binaries copied inside. These are uploaded to Docker Hub via the CI release process and include example docker-compose configuration files.

  12. Understand Consensus Spec Preset test coverage for Capella and Deneb

    stable

    The ConsensusSpecPreset-mainnet.md file provides a comprehensive list of test cases used to verify the Ethereum Consensus Specification (EF) implementation against the mainnet preset. These tests are categorized by Ethereum hardforks (e.g., Capella, Deneb) and specific functional areas like Epoch Processing, Inactivity, and Justification & Finalization.

    Key Test Categories

    Capella - Sanity - Blocks

    Verifies block transitions and state changes during the Capella era. Tests include:

    • Valid Transitions: attestation, attester_slashing, bls_change, deposit_in_block, voluntary_exit, and sync_committee operations.
    • Invalid Transitions: invalid_incorrect_state_root, invalid_parent_from_same_slot, invalid_prev_slot_block_transition, and various signature/slashing errors.

    Deneb - Epoch Processing

    Verifies logic executed at epoch boundaries during the Deneb era:

    • Effective Balance Updates: Tests hysteresis in effective balance updates.
    • Eth1 Data Reset: Ensures correct handling of Eth1 vote resets.
    • Inactivity Leakage: Extensive testing of inactivity scores, including random participation and leaking scenarios.
    • Justification & Finalization: Tests various support levels (e.g., 123_ok_support, 12_poor_support) and balance thresholds.
    • Participation Flags: Verifies how participation flags are updated (e.g., current_epoch_zeroed, previous_filled).
    • RANDAO: Verifies the resetting of RANDAO mixes.