# conflux-rust: the Conflux node written as a Cargo workspace

> conflux-rust is the Rust implementation of the Conflux protocol, organised as a large Cargo workspace of node binaries, client libraries, database layers, an execution VM and RPC crates. Its integration test suite is Python, and the project pins specific test vectors to specific git revisions.

**Conflux-Chain/conflux-rust** — The official Rust implementation of Conflux protocol. https://doc.confluxnetwork.org

- Repository: https://github.com/Conflux-Chain/conflux-rust
- Website: https://doc.confluxnetwork.org
- Stars: 717 · Forks: 220
- Language: Rust
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/conflux-chain-conflux-rust

## What this repository is, and who it is for

The README describes conflux-rust as a Rust based implementation of the Conflux protocol, and the repository description calls it the official Rust implementation, pointing at the documentation site doc.confluxnetwork.org. There is no ambiguity about the audience. The README splits its guidance into a For Users section, which points at the Conflux documentation for installing and running the node, and a For Developers section, which points at a project layout document for an overview of the crates. So the repository is the node implementation, not a library you would add as a dependency, and the two audiences are the people who operate a node and the people who change the client. Protocol level changes are handled separately: the README says that to propose significant changes to the Conflux protocol you should submit a CIP, with the CIPs kept in their own repository.

## A workspace split into bins, clients, storage and execution

The Cargo.toml is a workspace with resolver = 2 and the tools directory excluded, and its member list is where the architecture becomes legible. The binaries are bins/cfx_store, bins/cfx_key and bins/conflux. Under crates/ sit the client libraries cfx_bytes, cfx_types, cfx_addr, cfx_crypto, accounts, primitives, network, secret_store and transactiongen, alongside a stratum crate. The storage side is layered: crates/dbs/db is the interface, crates/dbs/kvdb-rocksdb is a RocksDB backed implementation, and dbs/db-errors, dbs/statedb and dbs/storage sit alongside it. Execution has its own group, crates/execution/executor, vm-interpreter, vm-types, solidity-abi and geth-tracer, and RPC is split into rpc-primitives, rpc-eth-types, rpc-cfx-types and rpc-eth-api. The util directory holds a long tail of general purpose crates, from util/dag and util/heap-map to util/metrics and util/throttling. Reading that member list tells you the client separates consensus facing types from execution facing ones, which is the usual shape for a chain that runs more than one virtual machine path.

## Unit tests live with the code, integration tests do not

The testing story is split in two, and the split is explicit in the README. Unit tests come together with the Rust code and are invoked with a single cargo command.

```bash
cargo test --release --all
```

Integration tests are a different animal: Python test scripts with the _test.py suffix, in the tests directory and in the integration_tests/tests directory. Running them takes five preparation steps, and the order matters because later steps depend on earlier ones. You set up and activate a new virtual environment, install the Python packages, compile Conflux in release mode, compile the consensus_bench binary separately, and fetch all submodules.

```bash
source ./dev-support/activate_new_venv.sh
```

```bash
bash ./dev-support/dep_pip3.sh
```

```bash
cargo build --release
```

```bash
cd tools/consensus_bench && cargo build --release
```

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

The virtual environment script creates a new one with Python 3.11 in .venv and activates it each time you run it, and you can also activate the created one directly with .venv/bin/activate. Once the preparation is done, the two suites are run separately, since they live in different directories.

```bash
python3 tests/test_all.py
```

```bash
pytest ./integration_tests/tests -vv -n 6 --dist loadscope
```

The pytest invocation runs with six workers and the loadscope distribution mode, which keeps a given scope of tests on the same worker. That is the right shape for a blockchain test suite, where cases in the same area often share a chain state and cannot be run in parallel with each other.

## The Python harness pins external test vectors to exact revisions

The pyproject.toml explains why the integration tests are not self contained. The project is named conflux-rust-tests and requires Python 3.11 or newer. Alongside the usual test tooling, including pytest, pytest-xdist, pyyaml, numpy, requests, asyncio and websockets, it depends on conflux-web3 pinned at version 1.4.4 and jsonrpcclient pinned at 4.0.3. The interesting part is the tool.uv section. The hive-py dependency is overridden to a specific git revision of a repository that was later renamed, and two Ethereum test suites are pulled from git at pinned revs, ethereum-spec-evm-resolver and ethereum-execution-spec-tests. solc-select is pinned at 1.2.0 as well. The consequence for a contributor is that the test suite is reproducible against fixed upstream material, which is what you want from a consensus client, but it also means the harness depends on network access to those repositories and on the pinned revisions staying available.

## Building the client, and the version floor it imposes

The build instructions point at a document rather than restating the steps, and the one hard number given up front is the minimum supported Rust version, stated as 1.94. That is a recent toolchain requirement, so a machine with an older pinned toolchain will not build this without an update, and the repository carries a rust-toolchain.toml at the root, which is the file that normally pins the channel for a workspace like this. The formatting rule is short and mandatory: if you have modified any Rust code, run the cargo_fmt.sh script before committing to format the code and ensure consistent code style. The style configuration itself lives in rustfmt.toml, and the repository also carries deny.toml, which is the configuration used by cargo-deny to check dependency licences and advisories. Those two files together tell you that the project treats supply chain hygiene as part of the build, not as an afterthought.

## Release naming, tags and the state of the branch

The recent release tags show how the project ships. There is v3.1.0 as Conflux v3.1.0 from 2026-08-10, a matching v3.1.0-testnet build dated 2026-08-03, and v3.0.3-fix from 2026-05-19, which shows that patch releases on the previous series are still being cut after a minor version lands. The tag naming is not the standard version only convention, so any release automation that expects plain semver tags will need adjusting. The repository is not archived and the last push was on 2026-10-20, with master as the default branch, so development continues after the August tag. The tree also carries changelogs/, a CODEOWNERS file, a monitor.json, an internal_contract/ directory and a run/ directory, plus testdata/ for fixtures, which is the layout of a client that is expected to be run and inspected by people who are not the original authors.

## Where this repository is the wrong tool

Two situations rule it out. The first is building a dApp. The crates in this workspace exist to run a Conflux node, and the RPC crates expose the node's own interfaces rather than a curated client API for application developers, so a team that only needs to read chain data or submit transactions should look at the documented RPC surface instead of depending on the workspace. The second is the licensing and governance shape of the code itself. The project is licensed under the GNU General Public License v3.0, which for anyone embedding the code in a proprietary product is a decision that has to be made deliberately. Beyond that, the operational cost is real: a Rust toolchain at 1.94 or newer, submodules, a Python 3.11 environment, pinned git revisions for two external test suites, and a separate consensus_bench binary that has to be built on its own. Running a node is documented in the Conflux documentation; this repository is where the code behind it lives, and it is written for people who intend to change it.

## Conclusion

Adopt conflux-rust if you intend to run a Conflux node, audit the protocol implementation or contribute to the client, and you are comfortable with a workspace of several dozen crates and a Python integration harness pinned to external test vectors. Do not adopt it as a library for building on Conflux, since the crates are organised for the node rather than as a stable SDK, and do not expect a two command build, since the test path also needs submodules and a virtual environment. Before you start, read the project layout document under docs/repo, confirm your toolchain satisfies the stated minimum supported Rust version of 1.94, and fetch the submodules with git submodule update --remote --recursive --init before running the integration suite.

## FAQ

### How do I run the unit tests for conflux-rust?

Unit tests come together with the Rust code and the README says they are invoked with cargo test --release --all. Integration tests are separate, being Python scripts with the _test.py suffix in the tests and integration_tests/tests directories.

### What do I need before running the conflux-rust integration tests?

The README lists five steps: activate a new virtual environment with source ./dev-support/activate_new_venv.sh, install the Python packages with bash ./dev-support/dep_pip3.sh, compile with cargo build --release, compile the consensus_bench binary from tools/consensus_bench, and fetch the submodules with git submodule update --remote --recursive --init.

### What is the minimum supported Rust version for conflux-rust?

The README states the Minimum Supported Rust Version of the project is 1.94. The repository also carries a rust-toolchain.toml at the root.

### How are the Conflux protocol changes proposed?

The README says that to propose significant changes to the Conflux protocol you should submit a CIP, with the CIPs kept in a separate repository. Ordinary source contributions follow the guidelines in CONTRIBUTING.md.

### What licence is conflux-rust released under?

The README lists the project as licensed under the GNU General Public License v3.0, with the licence file in the repository root.

## Sources

- [Conflux-Chain/conflux-rust on GitHub](https://github.com/Conflux-Chain/conflux-rust)
- [License: GPL-3.0](https://github.com/Conflux-Chain/conflux-rust/blob/master/LICENSE)
- [Project website](https://doc.confluxnetwork.org)
- [README](https://github.com/Conflux-Chain/conflux-rust/blob/master/README.md)
- [Releases](https://github.com/Conflux-Chain/conflux-rust/releases)

---

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