---
tags: epf, lighthouse, ethereum
---

[TOC]

# Notes on Lighthouse Architecture

Below are my notes from investigating the [Lighthouse](https://github.com/sigp/lighthouse.git) code base, with a focus on understanding the CL client and eip-4844 functionalities.

## Dependencies

### [Tokio](https://crates.io/crates/tokio)

Tokio is an event-driven, non-blocking I/O platform for writing asynchronous I/O backed applications. It is used in Lighthouse for communication between asynchronous tasks.

## Beacon Node

**NOTE:** This diagram is not complete. My goal right now is to try to understand how the Lighthouse consensus layer works at a high level, so I have intentionally skipped some functionalities (metrics, validator etc), error paths and details. Any feedback is welcomed!


### **[`Main`](https://github.com/sigp/lighthouse/blob/8656d233270076d17c2c65c9036cc7109afe7b3d/lighthouse/src/main.rs#L538)**

Entry point of the Lighthouse program. Parses CLI args, network configs and pass all parameters to `beacon_node` constructor when the `beacon_node` subcommand is used.

### **[`ProductionBeaconNode` constructor](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/src/lib.rs#L56)**

- build the beacon chain
- create data path, db path and freezer db path in file system
- calculate the current slot ([code](https://github.com/sigp/lighthouse/blob/8656d233270076d17c2c65c9036cc7109afe7b3d/beacon_node/beacon_chain/src/builder.rs#L606))
- runs the fork choice rule to determine the head ([code](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/consensus/fork_choice/src/fork_choice.rs#L512))
- get the `head_block` and `head_state` from `store` ([code](https://github.com/sigp/lighthouse/blob/8656d233270076d17c2c65c9036cc7109afe7b3d/beacon_node/beacon_chain/src/builder.rs#L622))
- build all caches, including `community_caches`, `pubkey_cache`, `exit_cache`
- store the beacon chain in the database
- start the networking stack ([code](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/client/src/builder.rs#L536))
- build the channels for external comms
- launch libp2p service
- launch dervied network services
- [`Router`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/router/mod.rs#L27-L28): Handles messages received from the network and client and organises syncing. See [`Router`](https://hackmd.io/RUCGCQ5HSM66uo6aeYSn8A?both#Router) section below.
- [`AttestationService`](https://github.com/sigp/lighthouse/blob/8656d233270076d17c2c65c9036cc7109afe7b3d/beacon_node/network/src/subnet_service/attestation_subnets.rs#L60)
- [`SyncCommitteeService`](https://github.com/sigp/lighthouse/blob/88006735c4f490ed4e603c64bc23ffedae70811a/beacon_node/network/src/subnet_service/sync_subnets.rs#L35)
- create the [`NetworkService`](https://github.com/sigp/lighthouse/blob/8656d233270076d17c2c65c9036cc7109afe7b3d/beacon_node/network/src/service.rs#L169) and spawn the task
- start HTTP API & metrics server
- send a head update to execution engine ([code](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/client/src/builder.rs#L769))
- update execution engine forkchoice
- spawn a routine that tracks the status of the execution engines
- spawn a routine that removes expired proposer preparations.
- spawns a routine that polls the `exchange_transition_configuration` endpoint.
- spawn a routine which ensures the EL is provided advance notice of any block producers. ([code](https://github.com/sigp/lighthouse/blob/be4e261e7433e02983648f7d7d8f21f74d3fa9d8/beacon_node/beacon_chain/src/proposer_prep_service.rs#L18))
- spawn a routine which checks the validity of any optimistically imported transition blocks - *for merge transition* ([code](https://github.com/sigp/lighthouse/blob/034260bd99460d2f2aa7dfdeea277704ecfa908c/beacon_node/beacon_chain/src/otb_verification_service.rs#L106))

### [`Router`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/router/mod.rs#L70)

- handle all messages incoming from the network service.
- handle RPC related functionalities
- handle gossip (pubsub) messages and pass it down to the `Processor`. [code](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/router/mod.rs#L209)
- **[`Processor`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/router/processor.rs#L28)**
- processes validated and decoded messages from the network
- spawns a [`BeaconProcessor`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/beacon_processor/mod.rs#L903) "manager" task which checks the receiver end of the channel
- e.g. when a `BeaconBlockAndBlobsSidecars` message is received, it sends `WorkEvent<GossipBlockAndBlobsSidecar>` to a `mpsc` channel using an [`mpsc::Sender`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/router/processor.rs#L36). This is then handled by the `BeaconProcessor` below.

### [`BeaconProcessor`]()

Handles events produced by `beacon_processor_send` via a `mpsc` channel.

- [`spawn_worker`](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/beacon_processor/mod.rs#L1396): called by the "manager" task to spawns a blocking worker thread to process some `Work`.
- e.g. the `GossipBlockAndBlobsSidecar` Work type is handled [here](https://github.com/sigp/lighthouse/blob/1aec17b09c8d6b87c746127b13b1c9395cfd5fe2/beacon_node/network/src/beacon_processor/mod.rs#L1532)

### [Block Processing](https://github.com/sigp/lighthouse/blob/0cdd049da96f9970a057ea1b0555b065ff9066e4/consensus/state_processing/src/per_block_processing.rs#L100)

`per_block_processing` logic is another interesting area to look into as part of eip-4844 implementation, as it's now processes blob kzg commitments. [code](https://github.com/sigp/lighthouse/blob/0cdd049da96f9970a057ea1b0555b065ff9066e4/consensus/state_processing/src/per_block_processing.rs#L190)

#### Usage

`per_block_processing` is called in various places:
1. `beacon_chain/src/beacon_chain.rs`: unable to find reference
2. `beacon_chain/src/block_verification.rs`: used when:
- on startup
- handling `Work::ChainSegment`
- handling `Work::RpcBlock`
- handling `Work::GossipBlock`
- handling `Work::DelayedImportBlock`
4. `beacon_chain/src/fork_revert.rs`
5. `store/src/reconstruct.rs`
6. `consensus/state_processing/src/block_replyer.rs`