# filecoin-project/venus architecture

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

- Interactive diagram: https://gitdiagram.com/filecoin-project/venus
- Repository: https://github.com/filecoin-project/venus

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        CLI["CLI (cmd/)"]:::external
    end

    subgraph "API/Gateway"
        RPC["JSON-RPC Server"]:::api
        INS["Inspector API"]:::api
    end

    subgraph "Node Core"
        CORE["Core Loader & Registry"]:::core
        subgraph "Core Subsystems"
            CHAINSTORE["Chain Store"]:::storage
            CHAINSYNC["ChainSync"]:::core
            CONSENSUS["Consensus Engine"]:::core
            MSGPOOL["MessagePool"]:::core
            MARKET["Market Manager"]:::core
            PAYCH["Payment Channel Manager"]:::core
            WALLET["Wallet Manager"]:::core
            FVMRT["FVM Actor Runtime"]:::core
            VM["VM Dispatch & Runtime"]:::core
            NET["Network Stack"]:::network
            BEACON["Drand Beacon"]:::network
            CONFIG["Config & Repository"]:::storage
            METRIC["Metrics & Logging"]:::storage
            SHAPI["Shared API Definitions"]:::core
            SHACT["Shared Actors & Types"]:::core
            SHBS["Shared Blockstore & Datastore"]:::storage
            SHLP2P["Shared libp2p Exchange"]:::network
        end
    end

    cloud["P2P Network & Peers"]:::external
    FFI["Native Proof FFI Bindings"]:::native
    SCRIPTS["Dev Tools & Scripts"]:::external
    ASSETS["Fixtures & Assets"]:::storage

    CLI -->|calls RPC| RPC
    CLI -->|calls Inspector| INS
    RPC -->|invokes| CORE
    INS -->|invokes| CORE
    CORE --> CHAINSYNC
    CORE --> CONSENSUS
    CORE --> MSGPOOL
    CORE --> MARKET
    CORE --> PAYCH
    CORE --> WALLET
    CORE --> FVMRT
    CORE --> VM
    CORE --> NET
    CORE --> BEACON
    CORE --> CONFIG
    CORE --> METRIC
    CORE --> SHAPI
    CORE --> SHACT
    CORE --> SHBS
    CORE --> SHLP2P

    CHAINSYNC <--> CHAINSTORE
    CHAINSYNC <--> NET
    CONSENSUS --> FFI
    MSGPOOL <--> NET
    MARKET --> CHAINSTORE
    MARKET <--> NET
    PAYCH --> WALLET
    PAYCH --> CHAINSTORE
    FVMRT --> CHAINSTORE
    FVMRT --> VM
    VM --> CHAINSTORE
    NET <--> cloud
    BEACON --> cloud
    CONFIG --> ASSETS
    METRIC -->|"exports to Prometheus/Zap"| cloud
    SCRIPTS --> CLI

    click CLI "https://github.com/filecoin-project/venus/tree/master/cmd/"
    click RPC "https://github.com/filecoin-project/venus/blob/master/app/node/rpc.go"
    click INS "https://github.com/filecoin-project/venus/blob/master/app/node/inspector_api.go"
    click CORE "https://github.com/filecoin-project/venus/blob/master/app/node/builder.go"
    click CHAINSTORE "https://github.com/filecoin-project/venus/tree/master/pkg/chain/"
    click CHAINSYNC "https://github.com/filecoin-project/venus/tree/master/pkg/chainsync/"
    click CONSENSUS "https://github.com/filecoin-project/venus/tree/master/pkg/consensus/"
    click MSGPOOL "https://github.com/filecoin-project/venus/tree/master/pkg/messagepool/"
    click MARKET "https://github.com/filecoin-project/venus/tree/master/pkg/market/"
    click PAYCH "https://github.com/filecoin-project/venus/tree/master/pkg/paychmgr/"
    click WALLET "https://github.com/filecoin-project/venus/tree/master/pkg/wallet/"
    click FVMRT "https://github.com/filecoin-project/venus/tree/master/pkg/fvm/"
    click VM "https://github.com/filecoin-project/venus/tree/master/pkg/vm/"
    click NET "https://github.com/filecoin-project/venus/tree/master/pkg/net/"
    click BEACON "https://github.com/filecoin-project/venus/tree/master/pkg/beacon/"
    click CONFIG "https://github.com/filecoin-project/venus/tree/master/pkg/config/"
    click CONFIG "https://github.com/filecoin-project/venus/tree/master/pkg/repo/"
    click METRIC "https://github.com/filecoin-project/venus/tree/master/pkg/metrics/"
    click METRIC "https://github.com/filecoin-project/venus/tree/master/pkg/journal/"
    click SHAPI "https://github.com/filecoin-project/venus/tree/master/venus-shared/api/"
    click SHACT "https://github.com/filecoin-project/venus/tree/master/venus-shared/actors/"
    click SHACT "https://github.com/filecoin-project/venus/tree/master/venus-shared/types/"
    click SHBS "https://github.com/filecoin-project/venus/tree/master/venus-shared/blockstore/"
    click SHLP2P "https://github.com/filecoin-project/venus/tree/master/venus-shared/libp2p/exchange/"
    click FFI "https://github.com/filecoin-project/venus/tree/master/extern/filecoin-ffi/"
    click SCRIPTS "https://github.com/filecoin-project/venus/tree/master/venus-devtool/"
    click SCRIPTS "https://github.com/filecoin-project/venus/tree/master/scripts/"
    click ASSETS "https://github.com/filecoin-project/venus/tree/master/fixtures/assets/"

    classDef api fill:#bbdefb,stroke:#1e88e5
    classDef core fill:#c8e6c9,stroke:#388e3c
    classDef storage fill:#ffe0b2,stroke:#f57c00
    classDef network fill:#d1c4e9,stroke:#7e57c2
    classDef native fill:#fff59d,stroke:#fbc02d
    classDef external fill:#ef9a9a,stroke:#d32f2f
```
