# Venus: the Filecoin full node built around a distributed storage pool model

> Venus is a complete Go implementation of the Filecoin distributed storage network, designed for storage providers who want to share node infrastructure across a pool rather than run every component independently. Its build process requires native FFI compilation, and most operational documentation lives on an external site rather than in the repository.

**filecoin-project/venus** — Filecoin Full Node Implementation in Go

- Repository: https://github.com/filecoin-project/venus
- Website: https://venus.filecoin.io
- Stars: 2,056 · Forks: 495
- Language: Go
- License: NOASSERTION
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/filecoin-project-venus

## Venus as one of two Go implementations of the Filecoin protocol

Venus implements the Filecoin Distributed Storage Network specification, the same protocol described at spec.filecoin.io that Lotus also implements. Both nodes can participate in the same Filecoin network, but Venus and Lotus differ in how they structure the node components a storage provider has to operate.

Venus is built around a distributed storage pool model. Under that model, multiple storage providers share certain node infrastructure rather than each running a complete independent stack. The README names security, ease of use and the distributed storage pool as the distinguishing features, though it delegates the architecture detail to venus.filecoin.io/intro/#how-venus-works rather than describing it inline.

The README gives the node an alternate name: 启明星, which is the Chinese name for the planet Venus and translates roughly as Morning Star. That label reflects where the Venus project originated within the Filecoin ecosystem but has no effect on protocol behavior.

Version v1.20.0 was published on 2026-05-18, and v1.21.0-rc1 on 2026-09-26. The module path in go.mod is github.com/filecoin-project/venus.

## Module architecture: stand-alone repos handle different node roles

Venus is not a single self-contained binary that covers all node functions. The README states directly that Venus "loosely describes a collection of modules that work together to realize a fully featured Filecoin implementation," and those modules live in separate repositories. This repository, filecoin-project/venus, is the core node implementation, but a full deployment for storage mining requires additional component repositories that the README lists at venus.filecoin.io rather than inline.

That separation is a deliberate architecture decision. Storage providers participating in the pool model can rely on shared infrastructure for some roles, so they do not need to run every module themselves. Which components each provider runs locally is explained at venus.filecoin.io, not here.

Within this repository, the internal structure reflects a similar split. venus-shared/ contains data types and API definitions that the other Venus modules consume. venus-devtool/ holds code generators that produce CBOR serialization bindings, inline code, actor bundle entries and JSON-RPC API client stubs. The cmd/ directory contains the main command entry points, and pkg/ contains the protocol implementation packages. External native libraries live under extern/.

## Building Venus requires git submodule initialization and CGO compilation

No prebuilt binary download is described in this repository. Build instructions are at venus.filecoin.io/intro/, and what the Makefile reveals is that the build is not a simple one-command invocation.

Venus depends on native C code for BLS signature verification and storage proof handling. The Makefile sets both CGO_CFLAGS_ALLOW and CGO_CFLAGS to -D__BLST_PORTABLE__, which configures the BLST library for portable CPU-agnostic compilation rather than relying on platform-specific vector instructions. The FFI code that wraps those native libraries lives under extern/filecoin-ffi/, which is a git submodule and is not present in a default clone.

Initializing the submodule must happen before the FFI build step:

```bash
git submodule update --init --recursive
```

After that, make builds the FFI first and then the Go binary. The Makefile also defines several code generation targets: cborgen, gogen, inline-gen, api-gen, bundle-gen and state-type-gen. Those regenerate Go source files derived from actor specifications and API definitions. A developer working from a fresh clone runs make rather than invoking the Go toolchain directly.

## The filecoin-ffi dependency carries a pseudo-version timestamped September 2020

go.mod lists filecoin-ffi as `github.com/filecoin-project/filecoin-ffi v0.30.4-0.20200910194244-f640612a1a1f`. That is a Go pseudo-version. The three components are: a base version v0.30.4, a commit timestamp 20200910 (September 10, 2020), and a commit hash f640612a1a1f. Pseudo-versions arise when a dependency has not received a proper Go module version that tooling can track semantically.

The September 2020 timestamp means filecoin-ffi has not carried a clean Go module version in over six years. Go tooling that checks for outdated dependencies treats pseudo-versions differently from properly versioned packages, and dependency auditing tools may flag this entry. The situation is not unusual for a C extension library tightly coupled to a single consuming project, but it does mean that the version string requires manual inspection rather than automated upgrade tooling.

For upgrade planning, updating the FFI requires finding the correct commit and replacing the pseudo-version string in go.mod directly.

Go 1.25.7 is the minimum toolchain version, as stated in go.mod. Any build environment must meet that floor before the FFI compilation step can begin.

## go-f3, drand, memguard, and badger among the declared dependencies

Several dependencies in go.mod point to Filecoin protocol integrations. github.com/filecoin-project/go-f3 at v0.8.12 is the Fast Finality module, which handles the f3 consensus protocol layer. github.com/drand/drand/v2 at v2.0.6 provides the distributed randomness feed that Filecoin uses for leader election. github.com/drand/go-clients at v0.2.2 is the companion client library for that service. drand is an external service that a running node contacts; it is not embedded in the Venus binary.

github.com/awnumar/memguard at v0.22.2 is also listed. The README does not document which Venus components use it.

github.com/dgraph-io/badger/v2 at v2.2007.4 is the embedded key-value store, providing local block and state storage without a separate database process. github.com/filecoin-project/go-jsonrpc at v0.1.5 is the JSON-RPC library for the node API. github.com/filecoin-project/go-state-types at v0.19.0 provides the shared actor and state type definitions that multiple Filecoin project modules depend on. Older specs-actors versions are also listed in go.mod at v2.3.6 and v3.1.2, alongside other protocol modules.

## What the repository contains beyond the README

Venus's README is shorter than the module it describes. Build steps, node architecture, a list of related component repositories, and how to join a storage pool are all referenced via external links to venus.filecoin.io, and none of them are described in the repository text.

The repository does contain additional files not referenced in the README: CODEWALK.md is described by its name as a code tour, designdocs.md is present at the top level, and a docs/ directory exists. None of these are linked or summarized in the README. A first-time contributor has to find them independently.

For operators, this matters because the venus.filecoin.io documentation site is the primary reference for every deployment decision. If that site lags behind a Venus version or is unavailable, the repository provides no fallback for how to configure, start or upgrade the node. SECURITY.md is present at the repository root and is the stated channel for vulnerability reports, though its contents are not summarized in the README.

## Lotus implements the same protocol with a more monolithic deployment

Lotus, also under the filecoin-project organization, is the other full Go node implementation of the Filecoin specification. The Venus README explicitly names Lotus as a comparison point, stating that Venus's deployment is "quite different" from Lotus.

Lotus bundles more components into a single deployment unit. A Lotus operator runs a more self-contained node. A Venus deployment distributes responsibilities across multiple separate module repositories, with some components shared across all pool participants.

For a developer building API clients or RPC tooling against a Filecoin node, Lotus has more inline documentation and a longer track record of detailed per-version notes. Venus depends on go-jsonrpc at v0.1.5 for its own JSON-RPC API layer, the same underlying library in common use across the Filecoin project, so client code at the transport level can work with either node.

The choice is primarily organizational: Venus for shared pool infrastructure, Lotus for independent node operation or more thoroughly documented deployment paths.

## Contribution gate: golangci-lint, go fmt, and the FIP process for protocol changes

Patches that change Venus must pass golangci-lint. CI rejects unlinted pull requests, and the contributing guidelines name golangci-lint explicitly as a requirement. Running `go fmt` before submitting a PR is also specified in the guidelines. The CONTRIBUTING.md file at the repository root documents the full process.

Protocol-level changes take a different path. The contributing guidelines ask that any change affecting the Filecoin protocol first go through a Filecoin Improvement Proposal at github.com/filecoin-project/FIPs before a PR is opened. That gate prevents Venus-specific changes from diverging from the network specification.

Venus is dual-licensed under Apache 2.0 and MIT, with LICENSE-APACHE and LICENSE-MIT both at the repository root. The last push to the repository was on 2026-09-26.

## Conclusion

Venus is the better choice for Filecoin storage providers who want to participate in a shared node pool rather than run a fully independent deployment. Solo operators, especially those coming from Lotus, face a steep initial barrier: build instructions live on an external site, not in the repository, and the FFI submodule requires native CGO compilation that make handles. Before committing to Venus, confirm that the venus.filecoin.io documentation covers the specific version you are deploying, check that your toolchain meets the go 1.25.7 requirement, and verify that the pool infrastructure your organization wants to join still runs the same Venus module versions as this repository.

## FAQ

### What is Venus in Filecoin?

Venus is a full node implementation of the Filecoin distributed storage network, written in Go. It is built around a distributed storage pool model where multiple storage providers share certain node components rather than each running a fully independent stack.

### How does Venus differ from Lotus?

Both implement the same Filecoin protocol, but Venus uses a distributed pool model where storage providers share infrastructure, while Lotus bundles more components into a single independent deployment. The Venus README says the deployment models are quite different.

### How do I build Venus from source?

The README points to venus.filecoin.io/intro/ for build steps. At minimum, the build requires initializing the filecoin-ffi git submodule with `git submodule update --init --recursive` and then running make, because the FFI dependency requires native CGO compilation.

### What Go version does Venus require?

go.mod specifies go 1.25.7 as the minimum toolchain version.

### What license does Venus use?

Venus is dual-licensed under Apache 2.0 and MIT. Both files, LICENSE-APACHE and LICENSE-MIT, are at the repository root.

## Sources

- [filecoin-project/venus on GitHub](https://github.com/filecoin-project/venus)
- [Issues](https://github.com/filecoin-project/venus/issues)
- [Project website](https://venus.filecoin.io)
- [README](https://github.com/filecoin-project/venus/blob/master/README.md)
- [Releases](https://github.com/filecoin-project/venus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/filecoin-project-venus