How filecoin-project/venus works
Project type and purpose
• This is a full-stack, monolithic Go application implementing a Filecoin node (“Venus”). It provides:
• A CLI (cmd/…, main.go) for end users and scripts
• A long-running Node daemon (app/node, main.go) exposing RPC/Inspector APIs
• A suite of reusable libraries and submodules under pkg/… and venus-shared/…
Top-level components (directory indicators)
• cmd/: user-facing CLIs and integration tests
• app/node/: the core Node process (builder, env, RPC, inspector, init)
• pkg/: implementation of core subsystems (chain, consensus, messagepool, network, paych, market, wallet, etc.)
• venus-shared/: shared API definitions, data types, builtin actors for fullnode↔client RPCs
• extern/filecoin-ffi: C bindings for proofs
• venus-component/: standalone libp2p exchange component
• venus-devtool/: code generators and release tooling
• scripts/, tools/: build, test, conformance tools
Key insights from README
• Venus is a fully-featured Filecoin implementation with built-in mining, syncing, P2P networking, FVM execution.
• Emphasizes security, ease-of-use, modularity.
• Modules communicate over gRPC/JSON‐RPC APIs defined in venus-shared/api.
Main components
a. CLI Layer
– cmd/venus & subcommands
– Config & flags → connects to RPC server
b. API/Gateway
– JSON-RPC endpoint (cmd/rpc.go, app/node/rpc.go)
– Inspector API (app/node/inspector_api.go)
c. Node Core
– Builder & lifecycle (app/node/builder.go)
– Module registry & loader
d. Core Subsystems (pkg/…):
– ChainSync (pkg/chainsync)
– Chain store & content addressed data (pkg/chain, venus-shared/blockstore)
– Consensus (pkg/consensus)
– MessagePool (pkg/messagepool)
– Market & Payment Channels (pkg/market, pkg/paychmgr)
– Wallet manager (pkg/wallet)
– FVM Actor runtime (pkg/vm, pkg/fvm)
– Network stack (libp2p under pkg/net & venus-shared/libp2p)
– Proof FFI (extern/filecoin-ffi)
– Configuration & Repo (pkg/config, pkg/repo)
– Metrics & Logging (pkg/metrics, pkg/journal)
e. External Services & Dependencies
– drand beacon (pkg/beacon)
– libp2p DHT/pubsub peers
– Local datastore (FS or memory via pkg/repo/fsrepo)
– Proof parameter files, genesis (fixtures/assets)
Relationships & interactions
• CLI → RPC → Node Core → Subsystems
• Node Core performs:
• Block sync: ChainSync ↔ Chain store ↔ Network
• Block validation: Consensus ↔ FFI proofs
• Message propagation: MessagePool ↔ Network ↔ Peers
• Market deals: Market manager ↔ Blockstore ↔ Network
• Payment channels: PaychMgr ↔ Wallet ↔ Chain
• FVM execution: VM ↔ Actor state in Chain store
• Configuration & Repo persist state to disk; metrics flows to Prometheus/Zap
Architectural patterns & design principles
• Modular plugin pattern: each subsystem implements well-defined interfaces
• Monolith with internal “microservices” loaded at runtime
• Clear separation: API layer vs. business logic vs. persistence vs. network
• Shared API packages enable code-gen for client & mock testing