DOCSEARCHbyAlgolia
Submit Docs

Lodestar Documentation

repository·unstable·Indexed 23 days ago

https://github.com/chainsafe/lodestar

A TypeScript implementation of the Ethereum Consensus specification developed by ChainSafe Systems. Lodestar provides a suite of packages for running beacon nodes, managing validator clients, and interacting with the Beacon API. Key components include @lodestar/api for REST client access, @lodestar/config for network variables and fork schedules, @lodestar/params for spec constants, and @lodestar/era for reading and writing e2s files.

Tokens
120.7K
Snippets
174
Records
747
Agent score
80%

What's inside Lodestar

  1. Overview of Lodestar Ethereum Consensus Packages

    unstable

    Lodestar is a TypeScript implementation of the Ethereum Consensus specification. It is organized as a monorepo containing several specialized packages:

    • @chainsafe/lodestar: The Command-line tool (CLI).
    • @lodestar/api: A REST Client for the Ethereum Beacon API.
    • @lodestar/beacon-node: The Beacon-chain client.
    • @lodestar/config: Bundled Eth Consensus types and parameters.
    • @lodestar/db: Persistent Eth Consensus data read/write.
    • @lodestar/era: Era file handling for historical beacon chain data.
    • @lodestar/fork-choice: Beacon-chain fork choice logic.
    • @lodestar/logger: NodeJS logger for Lodestar binaries.
    • @lodestar/params: Eth Consensus network parameters.
    • @lodestar/reqresp: Eth Consensus Req/Resp protocol.
    • @lodestar/spec-test-util: Test harness for Eth Consensus spec tests.
    • @lodestar/state-transition: Eth Consensus beacon-state transition logic.
    • @lodestar/types: Eth Consensus TypeScript and SSZ types.
    • @lodestar/utils: Miscellaneous utility functions.
    • @lodestar/validator: Validator client.

  2. Overview of Lodestar

    unstable
    Lodestar is a TypeScript-based Ethereum consensus client developed by ChainSafe. It implements the Ethereum Proof of Stake (PoS) consensus mechanism, allowing validators to propose blocks and attest to the validity of blocks proposed by others. As a consensus client, it is a critical component for maintaining network integrity, finality, and security on the Ethereum network.

  3. Overview of lodestar-logger

    unstable
    The lodestar-logger package provides a common NodeJS logging implementation used across Lodestar binaries. It is specifically designed to ensure that worker-threads can instantiate new loggers with consistent settings, maintaining uniform log formats and configurations throughout the application lifecycle.

  5. Overview of Lodestar Validator

    unstable
    Lodestar Validator is a TypeScript implementation of the Ethereum Consensus validator client. It is designed to allow developers to submit their own beacon nodes, databases, or loggers that are compatible with the eth-consensus API. It adheres to the Ethereum Consensus Spec v1.5.0 and is built using ES2021 standards.

  6. Overview of Lodestar Monorepo Packages

    unstable

    Lodestar is organized as a monorepo containing several specialized packages. Understanding these packages helps in identifying which module to use for specific tasks like API interaction, data persistence, or validator management.

    Core Packages

    • @chainsafe/lodestar: The CLI entrypoint that combines everything for running and configuring the beacon node and validator.
    • @lodestar/api: A TypeScript REST client for the Ethereum Consensus API.
    • @lodestar/beacon-node: The core beacon node process and the 'brain' of the implementation.
    • @lodestar/config: A unified configuration object combining @lodestar/params and @lodestar/types.
    • @lodestar/db: Handles all persistent data storage for the beacon node.
    • @lodestar/fork-choice: Manages reading and writing the fork choice DAG.
    • @lodestar/logger: A common NodeJS logger used across Lodestar binaries and worker threads.
    • @lodestar/params: Contains network configuration parameters (e.g., mainnet params).
    • @lodestar/reqresp: TypeScript implementation of the Ethereum Consensus Req/Resp protocol.
    • @lodestar/state-transition: Implements the beacon state transition function and utility functions like computeEpochAtSlot.
    • @lodestar/types: Contains Ethereum Consensus SSZ types and data structures.
    • @lodestar/utils: Common utilities used across the monorepo.
    • @lodestar/validator: The validator client, which communicates with the @lodestar/beacon-node REST API.

  8. Use BLS utility libraries

    unstable

    For BLS (Boneh-Lynn-Shacham) signature and key management, use the following libraries:

    • bls: Ethereum Consensus BLS sign, verify, and aggregate functionality.
    • bls-keystore: Store and retrieve a BLS secret key from an EIP-2335 JSON keystore.
    • bls-keygen: Utility functions to generate BLS secret keys following EIP-2333 and EIP-2334.
    • bls-hd-key: Low-level EIP-2333 and EIP-2334 functionality.

  9. Use Lodestar monorepo libraries

    unstable

    The Lodestar project provides several TypeScript packages that can be used independently of the CLI to build Ethereum consensus-related applications. Key monorepo libraries include:

    • params: Contains Ethereum consensus constants and fork names.
    • types: Provides Ethereum consensus types, TypeScript interfaces, and SSZ type objects.
    • config: Handles Ethereum consensus run-time network configuration.
    • api: An Ethereum consensus REST API client.

  12. What is Fast Confirmation and when to use it

    unstable

    Fast Confirmation is an experimental fork-choice extension in Lodestar that provides a confirmed block signal. This signal is stronger than the head (the most optimistic view) but weaker than finalized (the strongest settlement signal via FFG).

    It is designed for consumers that need faster operational safety signals than finality provides, such as:

    • Bridges: Deciding when a source-chain event is safe enough to relay.
    • Exchanges: Deciding when a deposit is safe to credit internally.
    • Custodians/Settlement Systems: Measuring how far the node's safe view lags behind the head.

    Safety Hierarchy

    1. head: Most optimistic; can move quickly.
    2. confirmed: Stronger than head, but may still move or reset after a reorg.
    3. finalized: Strongest settlement signal with full FFG safety guarantees.