Skip to content

Beacon Node Module Architecture

Lodestar Beacon Node Modules

When lodestar beacon --network NETWORK_NAME (as described in CLI Reference) is ran, @chainsafe/lodestar-cli does the following:

  • gathers data required to run the beacon node based on local configurations and CLI options
  • bootstraps the BeaconNode (in the node module) in @chainsafe/lodestar

The node then bootstraps the other modules. Within @chainsafe/lodestar, there are several modules that are started by the node process that bootstraps the beacon node:


  • various REST API calls that can be made for:
  • beacon
    • get data about the beacon state and publish new data
  • events
    • sets up an event stream to listen for new beacon node events
  • node
    • get data about the node process that is running Lodestar
  • validator
    • perform (and get relevant data for) validator duties
  • based on


  • processing block and attestation data to/from the beacon chain


  • handles all persistent data stored to the local leveldb while running the beacon chain. uses @chainsafe/lodestar-db under the hood.


  • handles all interactions with the eth1 blockchain (e.g. deposit data)




  • contains the nodeJS process that bootstraps and runs Lodestar
  • contains the entrypoint that @chainsafe/lodestar-cli calls to start the beacon node


  • "syncing" is the process by which the beacon node stays updated with new data published on eth2. there are two such processes in Lodestar:
  • initial sync
    • sync new data until we reach the head of the chain
  • regular sync
    • once we have finished initial sync (i.e. reached the head of the chain), regular sync keeps us updated in realtime as the chain head moves forward



  • various utility functions used by all of the above

Beacon Node Data Flow

Entry Paths for Data

There are a few paths that data can be brought into the beacon chain via outside sources:

  • via api
  • a validator can be proposing a new block
  • via network
  • req/resp - we can be explicitly requesting a block
  • gossip - we receive a block propagating across the network

Data Flow Diagram

Here's a diagram of how data flows across the modules of the beacon node. Click on a module or package in the diagram to see where it exists in the lodestar repo.

graph TD lodestar-validator(lodestar-validator) click lodestar-validator "" lodestar-validator-->|proposes block|api api:::nodemodule chain:::nodemodule db:::nodemodule eth1:::nodemodule network:::nodemodule sync:::nodemodule api-->|block data|db api-->|block data|lodestar-validator api-->|proposed block|network api-->|proposed block|chain api-->|attestation subnet subscription|sync lodestar-fork-choice(lodestar-fork-choice) click lodestar-fork-choice "" chain-->|get/set DAG|lodestar-fork-choice chain-->|block data|api eth1-->|eth1 deposit data|chain sync-->|block data|db sync-->|sync status & attestation subnet subscription|network sync-->|block data|chain sync-->|sync status|api chain-->|block data|db chain-->|checkpoint/block|sync peers([gossip peers]) network-->|peer data|sync network-->|proposed block|peers peers-->|incoming block|network db-->lodestar-db[(lodestar-db)] click lodestar-db "" click api "" click chain "" click db "" click eth1 "" click network "" click sync "" classDef nodemodule fill:grey,stroke-width:2px,stroke:black,color:white; linkStyle default stroke:grey, fill:none,stroke-width:1.5px; classDef lodestarpkg color:black, fill:#FFF566,stroke:black, stroke-width: 1.5px; class lodestar-fork-choice,lodestar-validator,lodestar-db lodestarpkg; style peers color: black, fill:#bbf, stroke-width:2px, color:#fff, stroke-dasharray: 5 5;