From e6160e847ac1983a7e5e318ecf4325c08ffe29b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 6 Mar 2026 19:15:44 -0300 Subject: [PATCH 1/3] docs: add interactive architecture diagram --- ethlambda_architecture.html | 1173 +++++++++++++++++++++++++++++++++++ 1 file changed, 1173 insertions(+) create mode 100644 ethlambda_architecture.html diff --git a/ethlambda_architecture.html b/ethlambda_architecture.html new file mode 100644 index 0000000..4fac6b3 --- /dev/null +++ b/ethlambda_architecture.html @@ -0,0 +1,1173 @@ + + + + + +ethlambda — Architecture + + + + +
+ + + + +
+ + +
+
+ + + + + + + + + + + +
+
main (tokio::main)
bin/ethlambda
+
+ + +
+
BlockChain (Actor)
spawned-concurrency 0.5
+
+ + +
+
P2P (Actor)
spawned-concurrency 0.5
+
+ + +
+
RPC Server
Axum HTTP :5054
+
+ + +
+
network-api
Recipient<M> messages
+
+ + +
+
Store (fork choice)
state + attestations
+
+
+
KeyManager
XMSS signing
+
+
+
LMD GHOST
fork_choice crate
+
+
+
State Transition
process_slots + process_block
+
+ + +
+
SwarmAdapter
tokio task + SwarmHandle
+
+
+
GossipSub
blocks + attestations
+
+
+
Req/Resp
Status + BlocksByRoot
+
+ + +
+
RocksDB Backend
Arc<dyn StorageBackend>
+
+
+
XMSS Crypto
leansig + leanVM
+
+ + +
+ InitP2P / InitBlockChain +
+ + +
+ BlockChain Actor (blockchain crate) +
+
+ P2P Actor (p2p crate) +
+
+ Shared Infrastructure +
+
+
+ + +
+
+ + + + + + + + + + +
+
+
STEP 1 · SWARM
+
GossipSub Receive
+
SwarmAdapter captures
event from libp2p mesh
+
+
+ +
+
+
STEP 2 · P2P ACTOR
+
Decode & Verify
+
WrappedSwarmEvent →
snappy + SSZ + XMSS verify
+
+
+ +
+
+
STEP 3 · NETWORK-API
+
NewBlock Message
+
Recipient<NewBlock>
typed actor message
+
+
+ +
+
+
STEP 4 · PURE FUNCTIONS
+
State Transition
+
process_slots()
process_block()
update justification
+
+
+ +
+
+
STEP 5 · FORK CHOICE
+
LMD GHOST Head
+
recompute head
weight attestations
update safe target
+
+
+ +
+
+
STEP 6 · STORAGE
+
RocksDB Persist
+
atomic WriteBatch
headers + bodies + sigs
+
+
+ +
+
+
TICK SYSTEM · 800ms
+
Validator Duties
+
Interval 0: propose
Interval 1: attest
Interval 2: safe target
Interval 3/4: accept atts
+
+
+ +
+
+
AGGREGATION
+
XMSS Aggregate
+
leanVM aggregation
gossip signatures → proofs
+
+
+ +
+
+
PUBLISH
+
Gossip Publish
+
Recipient<PublishBlock>
→ SwarmHandle.publish()
+
+
+
+
+ + +
+
+ +
+
+
Bin
+
+
Entry Point
+
CLI, config, spawns actors, wires Recipient handles via init messages
+
+
bin/ethlambda/
+
+
+ main.rs (tokio::main) + checkpoint_sync.rs + version.rs (vergen-git2) +
+
+ +
+
+
BC
+
+
Blockchain (Consensus Actor)
+
Actor: fork choice, state transition, validator duties, tick system
+
+
crates/blockchain/
+
+
+ BlockChainServer (#[actor]) + Store (fork choice state) + KeyManager (XMSS signing) + fork_choice (LMD GHOST) + state_transition (STF) + Tick system (800ms intervals) + Handler<NewBlock> + Handler<InitP2P> +
+
+ +
+
+
Net
+
+
Networking (P2P Actor + RPC)
+
Actor + SwarmAdapter bridge, GossipSub, Req/Resp, Axum HTTP
+
+
crates/net/
+
+
+ P2PServer (#[actor]) + SwarmAdapter (tokio task) + SwarmHandle (command channel) + GossipSub (blocks + attestations) + Req/Resp (Status + BlocksByRoot) + Handler<PublishBlock> + Handler<InitBlockChain> + RPC (Axum /lean/v0/*) + Prometheus /metrics +
+
+ +
+
+
API
+
+
Network API (Message Contract)
+
Typed messages shared between actors: NewBlock, PublishBlock, InitP2P, etc.
+
+
crates/net/api/
+
+
+ PublishBlock / PublishAttestation + NewBlock / NewAttestation + FetchBlock + InitP2P / InitBlockChain + PublishAggregatedAttestation +
+
+ +
+
+
DB
+
+
Storage
+
RocksDB backend, trait-based API, atomic write batches
+
+
crates/storage/
+
+
+ RocksDBBackend + StorageBackend trait + StorageReadView / StorageWriteBatch + 10 Tables + Store (wraps backend + state) +
+
+ +
+
+
Sig
+
+
Cryptography
+
XMSS post-quantum signatures, leanVM aggregation
+
+
crates/common/crypto/
+
+
+ XMSS sign/verify (leansig) + Signature aggregation (leanVM) + 52B pubkeys, 3112B signatures +
+
+ +
+
+
T
+
+
Core Types
+
SSZ-encoded data structures: State, Block, Attestation, Checkpoint
+
+
crates/common/types/
+
+
+ State / Block / Attestation + SignedBlockWithAttestation + Checkpoint (root + slot) + GenesisConfig + ShortRoot (truncated display) +
+
+
+
+ + +
+
+ + + + + + + + + + + + +
+
bin/ethlambda
entry point + CLI
+
+ + +
+
ethlambda-blockchain
Actor + store + tick
+
+
+
ethlambda-p2p
Actor + SwarmAdapter
+
+
+
ethlambda-rpc
Axum HTTP + /metrics
+
+ + +
+
ethlambda-network-api
message contract crate
+
+
+
ethlambda-fork-choice
LMD GHOST (3SF-mini)
+
+
+
ethlambda-state-transition
process_slots + process_block
+
+
+
ethlambda-storage
RocksDB + trait API
+
+ + +
+
ethlambda-crypto
XMSS + leansig
+
+
+
ethlambda-types
State, Block, Attestation
+
+
+
ethlambda-metrics
Prometheus re-exports
+
+
+
spawned-concurrency 0.5
Actor + Recipient framework
+
+ + +
+ Consensus Sub-crates +
+
+ Common / Shared +
+
+
+
+ + +
+
+ + + + From 41a52f64d76eaba4758504082dd6eccfa562d013 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 6 Mar 2026 19:22:20 -0300 Subject: [PATCH 2/3] chore: move file to docs/infographics --- .../infographics/ethlambda_architecture.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename ethlambda_architecture.html => docs/infographics/ethlambda_architecture.html (99%) diff --git a/ethlambda_architecture.html b/docs/infographics/ethlambda_architecture.html similarity index 99% rename from ethlambda_architecture.html rename to docs/infographics/ethlambda_architecture.html index 4fac6b3..cc674fd 100644 --- a/ethlambda_architecture.html +++ b/docs/infographics/ethlambda_architecture.html @@ -298,7 +298,7 @@

ethlambda

-
+
network-api
Recipient<M> messages
@@ -336,7 +336,7 @@

ethlambda

-
+
InitP2P / InitBlockChain
From 1cef6e89c6d65fc7f993f6e3ea76e3c2312b9cc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 6 Mar 2026 19:27:05 -0300 Subject: [PATCH 3/3] chore: clean up a little --- docs/infographics/ethlambda_architecture.html | 55 ++++++------------- 1 file changed, 17 insertions(+), 38 deletions(-) diff --git a/docs/infographics/ethlambda_architecture.html b/docs/infographics/ethlambda_architecture.html index cc674fd..cce7229 100644 --- a/docs/infographics/ethlambda_architecture.html +++ b/docs/infographics/ethlambda_architecture.html @@ -136,6 +136,7 @@ .node { position: absolute; border-radius: 8px; cursor: pointer; transition: transform 0.15s, box-shadow 0.15s; user-select: none; + z-index: 2; } .node:hover { transform: translateY(-2px) scale(1.02); z-index: 10; } .node.selected { z-index: 10; } @@ -161,14 +162,14 @@ .api-node .node-inner { background: linear-gradient(135deg, rgba(26,188,156,0.2), rgba(20,143,119,0.12)); border-color: rgba(26,188,156,0.4); } .api-node.selected .node-inner, .api-node:hover .node-inner { border-color: var(--api); box-shadow: 0 0 12px rgba(26,188,156,0.3); } - .group-box { position: absolute; border-radius: 12px; border: 1px dashed; pointer-events: none; } + .group-box { position: absolute; border-radius: 12px; border: 1px dashed; pointer-events: none; z-index: 1; } .group-label { position: absolute; top: -11px; left: 14px; font-size: 10px; font-weight: 700; letter-spacing: 1px; text-transform: uppercase; padding: 2px 8px; border-radius: 4px; } #view-actors { padding: 32px; } - .actors-canvas { position: relative; width: 900px; height: 560px; margin: 0 auto; } + .actors-canvas { position: relative; width: 970px; height: 560px; margin: 0 auto; } #view-flow { padding: 32px; } .flow-canvas { position: relative; width: 920px; height: 620px; margin: 0 auto; } @@ -278,7 +279,7 @@

ethlambda

-
+
main (tokio::main)
bin/ethlambda
@@ -288,17 +289,17 @@

ethlambda

-
+
P2P (Actor)
spawned-concurrency 0.5
-
+
RPC Server
Axum HTTP :5054
-
+
network-api
Recipient<M> messages
@@ -317,37 +318,37 @@

ethlambda

-
+
SwarmAdapter
tokio task + SwarmHandle
-
+
GossipSub
blocks + attestations
-
+
Req/Resp
Status + BlocksByRoot
-
+
RocksDB Backend
Arc<dyn StorageBackend>
-
+
XMSS Crypto
leansig + leanVM
-
+
InitP2P / InitBlockChain
-
+
BlockChain Actor (blockchain crate)
-
+
P2P Actor (p2p crate)
-
+
Shared Infrastructure
@@ -629,9 +630,7 @@

ethlambda

ethlambda-metrics
Prometheus re-exports
-
-
spawned-concurrency 0.5
Actor + Recipient framework
-
+
@@ -906,23 +905,6 @@

ethlambda

tags: ['Recipient', 'SwarmHandle', 'outbound'], details: ['Recipient -> Handler -> SwarmHandle.publish()', 'SSZ + snappy before publish'], }, - spawned: { - title: 'spawned-concurrency 0.5', - subtitle: 'external crate (LambdaClass)', - lang: 'entry', - desc: 'OTP-inspired actor framework for Rust, version 0.5. Provides Actor/Handler traits, ActorRef, typed Recipient for cross-actor messaging, Context for self-scheduling, and spawn_listener for bridging async streams into actor mailboxes.', - tags: ['Actor', 'Handler', 'Recipient', 'Context', '#[actor]'], - details: [ - 'Actor trait + #[actor] macro: define actor state + handlers', - '#[protocol] macro: generates message types for internal use', - 'Handler: async handle(&mut self, msg, ctx) for each message', - 'ActorRef: typed handle to send messages to actor A', - 'Recipient: type-erased handle for message M (cross-actor)', - 'Context: self-reference for send_after() scheduling', - 'spawn_listener(): bridge Stream into actor mailbox', - 'send_after(duration, ctx, msg): delayed message delivery', - ], - }, 'consensus-layer': { title: 'Blockchain (Consensus Layer)', subtitle: 'crates/blockchain/', @@ -1140,9 +1122,6 @@

ethlambda

['dn-stf', 'dn-crypto', 'bottom', 'top', DC, 'darr-crypto', false], ['dn-storage', 'dn-types', 'bottom', 'top', DC, 'darr-dim', false], ['dn-storage', 'dn-metrics', 'bottom', 'top', SC, 'darr-storage', false], - ['dn-blockchain', 'dn-spawned', 'right', 'left', RC, 'darr-rust', false], - ['dn-p2p', 'dn-spawned', 'right', 'left', RC, 'darr-rust', false], - ['dn-netapi', 'dn-spawned', 'right', 'left', RC, 'darr-rust', false], ['dn-netapi', 'dn-types', 'bottom', 'top', DC, 'darr-dim', false], ]; edges.forEach(([fromId, toId, exitSide, enterSide, color, marker, animated]) => {