# lambdaclass/ethlambda architecture

> Architecture diagram of the GitHub repository lambdaclass/ethlambda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lambdaclass/ethlambda
- Repository: https://github.com/lambdaclass/ethlambda

## Overview

ethlambda is a Rust Lean Ethereum consensus client. Its principal workflow is to connect to peers, receive blocks and attestations, process state transitions and fork choice, persist chain state, and produce validator attestations or blocks for gossip. The map also includes the separately runnable event monitor, which collects node events and serves a dashboard. README capabilities guide coverage; sampled excerpts confirm selected startup, storage, networking, and monitor paths, so uncertain internal wiring is omitted.

Main entry points: [`crates/blockchain/src/lib.rs`](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/lib.rs) (Chain Runtime), [`bin/ethlambda/src/main.rs`](https://github.com/lambdaclass/ethlambda/blob/main/bin/ethlambda/src/main.rs) (Node Startup), [`crates/net/p2p/src/lib.rs`](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/lib.rs) (P2P Service), [`crates/net/p2p/src/req_resp/handlers.rs`](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/req_resp/handlers.rs) (Request Responses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Runtime"]
  node_main["Node Startup<br/>[main.rs]"]
  node_cli["CLI Commands<br/>[command.rs]"]
end

subgraph group_consensus["Consensus Processing"]
  node_types["Consensus Types<br/>[lib.rs]"]
  node_crypto["Signing Crypto<br/>[lib.rs]"]
  node_blockchain["Chain Runtime<br/>[lib.rs]"]
  node_transition["State Transition<br/>[lib.rs]"]
  node_forkchoice["Fork Choice<br/>[lib.rs]"]
  node_builder["Block Building<br/>[block_builder.rs]"]
  node_aggregation["Attestation Aggregation<br/>[aggregation.rs]"]
  node_keys["Validator Keys<br/>[key_manager.rs]"]
  node_storage[("Chain Store<br/>[store.rs]")]
end

subgraph group_network["Peer Networking"]
  node_p2p["P2P Service<br/>[lib.rs]"]
  node_gossip["Gossip Handlers<br/>[handler.rs]"]
  node_reqresp["Request Responses<br/>[handlers.rs]"]
end

subgraph group_interfaces["Node Interfaces"]
  node_rpc["RPC Service<br/>[lib.rs]"]
  node_metrics["Metrics<br/>[lib.rs]"]
end

subgraph group_monitor["Event Monitor"]
  node_monitor_main["Monitor Startup<br/>[main.rs]"]
  node_collector["Node Collectors<br/>[collector.rs]"]
  node_hub["Event Hub<br/>[hub.rs]"]
  node_monitor_server["Dashboard Server<br/>[server.rs]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
end

node_operator(("Operator"))
node_peers(("Consensus Peers"))
node_validators(("Validators"))

node_operator -->|"invokes"| node_cli
node_cli -->|"selects command"| node_main
node_main -->|"starts node"| node_blockchain
node_main -->|"initializes P2P"| node_p2p
node_main -->|"starts service"| node_rpc
node_blockchain -->|"processes blocks"| node_transition
node_blockchain -->|"selects head"| node_forkchoice
node_blockchain -->|"builds blocks"| node_builder
node_blockchain -->|"aggregates votes"| node_aggregation
node_blockchain -->|"signs duties"| node_keys
node_keys -->|"signs with"| node_crypto
node_transition -->|"processes"| node_types
node_forkchoice -->|"evaluates votes"| node_types
node_blockchain -->|"reads and writes"| node_storage
node_p2p -->|"dispatches messages"| node_gossip
node_p2p -->|"dispatches requests"| node_reqresp
node_peers -->|"exchanges messages"| node_p2p
node_gossip -->|"delivers consensus data"| node_blockchain
node_reqresp -->|"reads chain data"| node_storage
node_reqresp -->|"responds to requests"| node_peers
node_validators -->|"supplies duties"| node_main
node_rpc -->|"serves node data"| node_blockchain
node_blockchain -->|"records metrics"| node_metrics
node_monitor_main -->|"starts collectors"| node_collector
node_collector -->|"publishes events"| node_hub
node_monitor_main -->|"serves dashboard"| node_monitor_server
node_monitor_server -->|"streams events"| node_hub
node_dashboard -->|"fetches and streams"| node_monitor_server

click node_main "https://github.com/lambdaclass/ethlambda/blob/main/bin/ethlambda/src/main.rs"
click node_cli "https://github.com/lambdaclass/ethlambda/blob/main/bin/ethlambda/src/command.rs"
click node_types "https://github.com/lambdaclass/ethlambda/blob/main/crates/common/types/src/lib.rs"
click node_crypto "https://github.com/lambdaclass/ethlambda/blob/main/crates/common/crypto/src/lib.rs"
click node_blockchain "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/lib.rs"
click node_transition "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/state_transition/src/lib.rs"
click node_forkchoice "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/fork_choice/src/lib.rs"
click node_builder "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/block_builder.rs"
click node_aggregation "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/aggregation.rs"
click node_keys "https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/key_manager.rs"
click node_storage "https://github.com/lambdaclass/ethlambda/blob/main/crates/storage/src/store.rs"
click node_p2p "https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/lib.rs"
click node_gossip "https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/gossipsub/handler.rs"
click node_reqresp "https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/req_resp/handlers.rs"
click node_rpc "https://github.com/lambdaclass/ethlambda/blob/main/crates/net/rpc/src/lib.rs"
click node_metrics "https://github.com/lambdaclass/ethlambda/blob/main/crates/common/metrics/src/lib.rs"
click node_monitor_main "https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/main.rs"
click node_collector "https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/collector.rs"
click node_hub "https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/hub.rs"
click node_monitor_server "https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/server.rs"
click node_dashboard "https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/web/app.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli toneBlue
class node_types,node_crypto,node_blockchain,node_transition,node_forkchoice,node_builder,node_aggregation,node_keys,node_storage toneAmber
class node_p2p,node_gossip,node_reqresp toneMint
class node_rpc,node_metrics toneRose
class node_monitor_main,node_collector,node_hub,node_monitor_server,node_dashboard,node_operator,node_peers,node_validators toneIndigo
```

## Components

### Client Runtime

- [Node Startup](https://github.com/lambdaclass/ethlambda/blob/main/bin/ethlambda/src/main.rs): `bin/ethlambda/src/main.rs`
- [CLI Commands](https://github.com/lambdaclass/ethlambda/blob/main/bin/ethlambda/src/command.rs): `bin/ethlambda/src/command.rs`

### Consensus Processing

- [Consensus Types](https://github.com/lambdaclass/ethlambda/blob/main/crates/common/types/src/lib.rs): `crates/common/types/src/lib.rs`
- [Signing Crypto](https://github.com/lambdaclass/ethlambda/blob/main/crates/common/crypto/src/lib.rs): `crates/common/crypto/src/lib.rs`
- [Chain Runtime](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/lib.rs): `crates/blockchain/src/lib.rs`
- [State Transition](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/state_transition/src/lib.rs): `crates/blockchain/state_transition/src/lib.rs`
- [Fork Choice](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/fork_choice/src/lib.rs): `crates/blockchain/fork_choice/src/lib.rs`
- [Block Building](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/block_builder.rs): `crates/blockchain/src/block_builder.rs`
- [Attestation Aggregation](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/aggregation.rs): `crates/blockchain/src/aggregation.rs`
- [Validator Keys](https://github.com/lambdaclass/ethlambda/blob/main/crates/blockchain/src/key_manager.rs): `crates/blockchain/src/key_manager.rs`
- [Chain Store](https://github.com/lambdaclass/ethlambda/blob/main/crates/storage/src/store.rs): `crates/storage/src/store.rs`

### Peer Networking

- [P2P Service](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/lib.rs): `crates/net/p2p/src/lib.rs`
- [Gossip Handlers](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/gossipsub/handler.rs): `crates/net/p2p/src/gossipsub/handler.rs`
- [Request Responses](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/p2p/src/req_resp/handlers.rs): `crates/net/p2p/src/req_resp/handlers.rs`

### Node Interfaces

- [RPC Service](https://github.com/lambdaclass/ethlambda/blob/main/crates/net/rpc/src/lib.rs): `crates/net/rpc/src/lib.rs`
- [Metrics](https://github.com/lambdaclass/ethlambda/blob/main/crates/common/metrics/src/lib.rs): `crates/common/metrics/src/lib.rs`

### Event Monitor

- [Monitor Startup](https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/main.rs): `tooling/event-monitor/src/main.rs`
- [Node Collectors](https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/collector.rs): `tooling/event-monitor/src/collector.rs`
- [Event Hub](https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/hub.rs): `tooling/event-monitor/src/hub.rs`
- [Dashboard Server](https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/src/server.rs): `tooling/event-monitor/src/server.rs`
- [Dashboard UI](https://github.com/lambdaclass/ethlambda/blob/main/tooling/event-monitor/web/app.js): `tooling/event-monitor/web/app.js`

### Other components

- **Operator**
- **Consensus Peers**
- **Validators**

## Connections

- Operator → CLI Commands: invokes
- CLI Commands → Node Startup: selects command
- Node Startup → Chain Runtime: starts node
- Node Startup → P2P Service: initializes P2P
- Node Startup → RPC Service: starts service
- Chain Runtime → State Transition: processes blocks
- Chain Runtime → Fork Choice: selects head
- Chain Runtime → Block Building: builds blocks
- Chain Runtime → Attestation Aggregation: aggregates votes
- Chain Runtime → Validator Keys: signs duties
- Validator Keys → Signing Crypto: signs with
- State Transition → Consensus Types: processes
- Fork Choice → Consensus Types: evaluates votes
- Chain Runtime → Chain Store: reads and writes
- P2P Service → Gossip Handlers: dispatches messages
- P2P Service → Request Responses: dispatches requests
- Consensus Peers → P2P Service: exchanges messages
- Gossip Handlers → Chain Runtime: delivers consensus data
- Request Responses → Chain Store: reads chain data
- Request Responses → Consensus Peers: responds to requests
- Validators → Node Startup: supplies duties
- RPC Service → Chain Runtime: serves node data
- Chain Runtime → Metrics: records metrics
- Monitor Startup → Node Collectors: starts collectors
- Node Collectors → Event Hub: publishes events
- Monitor Startup → Dashboard Server: serves dashboard
- Dashboard Server → Event Hub: streams events
- Dashboard UI → Dashboard Server: fetches and streams