How vechain/thor works
Project Type and Purpose
• This is a Go-based Layer-1 blockchain node implementation (VeChainThor). It provides:
• A command-line interface (cmd/thor) to start and configure a node
• A P2P network layer to discover, connect and synchronize peers
• A consensus engine (PoA/BFT styles) to agree on and produce blocks
• A transaction pool, block builder and state machine (EVM compatible)
• REST/JSON-RPC APIs to serve clients and expose metrics
High-Level Architecture Analysis
• Top-level directories map to core subsystems:
• cmd/…: CLI entry points (“thor”, “disco”)
• api/: HTTP/JSON RPC API handlers and documentation
• p2psrv/, comm/: Peer discovery, RPC, gossip, sync logic
• consensus/, bft/, poa/: Consensus algorithms and forking logic
• txpool/: Pending transactions management and validation
• block/, chain/: Block assembly, chain persistence, forks
• runtime/, vm/: Smart‐contract execution environment (EVM)
• state/, logdb/: State trie, historical lookup, event logs
• builtin/: Native smart contracts preloaded at genesis
• metrics/: Prometheus, telemetry instrumentation
• tracers/: Transaction tracing and profiling tools
• Test and bench directories alongside each module confirm clear module boundaries.
Key Components
a. Node CLI (“thor” executable)
• Initialises configuration, bootstraps subsystems, launches services
b. P2P Network Layer (p2psrv + comm)
• Peer discovery (bootstrap nodes), secure RPC, gossip protocols
c. Consensus Engine (consensus/, bft/, poa/)
• Receives blocks, validates, participates in block production
• Fork-handling, justifier, metrics
d. Transaction Pool (txpool/)
• Accepts inbound transactions via API or peer
• Validates, prioritizes, caches for inclusion in blocks
e. Block Assembler (block/, packer/)
• Gathers transactions, builds header, computes roots
f. Chain Manager (chain/)
• Validates blocks, applies to state, persists in logdb and state trie
g. State Database (state/, runtime/statedb/, muxdb/, trie/)
• Ethereum-style Merkle-Patricia trie, backing key-value store
• Journal, snapshots, cache layers
h. EVM Runtime (vm/, runtime/)
• Executes smart contracts, built-in natives, energy metering
i. API Server (api/)
• JSON/REST endpoints for blocks, transactions, accounts, events, metrics
j. Instrumentation (metrics/, log/, tracers/)
• Exposes Prometheus metrics, structured logging, execution traces
Component Interactions and Data Flows
• Startup: CLI → load config → init modules in order: metrics → storage → trie → state → txpool → P2P → consensus → API
• Peer Sync: P2P ←→ comm RPCs → fetch block headers/bodies → chain manager → state DB
• Tx Propagation: API or P2P → txpool → broadcast to peers → block assembler
• Block Production: consensus engine triggers packer → build block → broadcast via P2P
• Block Finalization: receive block → consensus validation → chain.ApplyBlock → state.Update → logdb.Store
• Contract Execution: chain.ApplyBlock calls vm.InterpretTransaction → runtime(statedb) updates → emit events
• API Responses: chain, state, trx data → JSON serialization → client
• Metrics & Logging: hook into each module for counters, histograms, logs
Architectural Patterns and Principles
• Modular package per subsystem – clear separation of concerns
• Layered architecture: CLI → API → Consensus → Core Chain → State → Storage
• Interface‐based abstractions for networking, database (muxdb), VM
• Dependency injection for testing: modules expose interfaces and tests use mocks
• Event-driven flows: blocks, transactions, state changes produce events for subscriptions