diff --git a/docs/infographics/ethlambda_architecture.html b/docs/infographics/ethlambda_architecture.html new file mode 100644 index 00000000..cce72292 --- /dev/null +++ b/docs/infographics/ethlambda_architecture.html @@ -0,0 +1,1152 @@ + + + + + +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
+
+ + + +
+ Consensus Sub-crates +
+
+ Common / Shared +
+
+
+
+ + +
+
+ + + +