freenet-core: a Rust peer-to-peer platform for contracts and delegates

What freenet-core solves, and for whom

Freenet's pitch is that services should not sit behind a single operator. The README describes a peer-to-peer network that "transforms users' computers into a resilient, distributed platform on which anyone can build decentralized services", with every peer contributing to a fault-tolerant collective. The repository is the Rust implementation of that node: a workspace of crates, a set of test contracts, and a sample application under apps/freenet-ping.

The audience is narrow and technical. This is not a package you drop into an existing web app to add offline sync. It is the node software plus the contract tooling that a decentralized service would run on. If you write Rust and want to experiment with replicated application state without owning the servers, the layout here is what you would build against. If you want a hosted database or a managed backend, this is the wrong repository.

One design claim in the README is worth separating from the marketing around it: interoperability is framed as a default property, not an integration project. Whether that holds depends on the contract model described in the whitepaper, not on the README, which does not explain the model itself.

Contracts as idempotent commutative monoids: the actual model

The README points to the Freenet whitepaper for the architecture and names four pieces: a contract model built on "idempotent commutative monoids on application state", summary/delta synchronization, small-world adaptive routing, and a delegate model for private state. That is the whole of the architectural description in the repository's front page, and it is enough to see the shape of the design.

A contract holds application state. Because the merge operation is idempotent and commutative, the order in which updates arrive does not matter, and applying the same update twice changes nothing. That is what lets peers exchange summaries and deltas rather than full state, and it is why routing can be adaptive without a coordinator deciding who owns what. The delegate model is the counterpart for state that should not be replicated: private data stays with the delegate rather than becoming part of the shared contract.

The trade-off is real. Idempotent commutative merges are easy for sets, counters and similar structures, and awkward for anything that needs a strict order of operations or a linear history. If your application state is a document with edits that must be sequenced, you will be fighting the model rather than using it. The whitepaper is the place to check whether your data fits; the README does not discuss the constraint at all.

The workspace confirms the shape of the codebase. Cargo.toml lists members under crates/*, the freenet-ping app split into app, types and contracts/ping, and five integration test crates with names like test-contract-delta-trap and test-contract-update-nochange. Those test names read as contract-level behaviour checks rather than end-to-end network tests, which suggests the contract semantics are the part the project exercises most directly.

Building freenet-core from the repository

The README gives two install commands and nothing else. Both use cargo install with a path into the workspace, so you build from a checkout rather than pulling a binary.

To install the core node:

cargo install --path crates/core

To install fdev, the utility crate that sits alongside it:

cargo install --path crates/fdev

The README does not state what fdev does beyond calling it "the fdev utility", so expect to read crates/fdev to find out. It also does not document how to start a node, which ports it listens on, or where it stores state. The repository does include docker/ and a flake.nix, plus rust-toolchain.toml pinning the toolchain, so container and Nix paths exist in the tree even though the README does not walk through them.

For a first real use, the sample application is the honest starting point. The workspace includes apps/freenet-ping with its own contract crate, and the test crates under tests/ show how contracts are exercised in isolation. Running those tests is the closest thing to a documented first run:

cargo test -p test-contract-integration

The package name comes from the workspace member path tests/test-contract-integration. Expect contract-level assertions, not a running network. The README does not describe a quickstart beyond the two install commands, so anything past this point means reading the source.

Where freenet-core is the wrong tool

The documentation gap is the first limitation, and it is not cosmetic. The README covers what Freenet is, links the whitepaper, and gives two cargo install commands. It does not cover running a node, joining a network, configuring storage, monitoring a peer, or upgrading between releases. Releases are frequent, with v0.2.136 published on 2026-09-21 and v0.2.135 on 2026-09-10, and the README documents no upgrade path or compatibility policy. Frequent releases without a stated compatibility story means you should expect to read changelogs and source before moving between versions.

The contribution policy is a second signal about maturity. The README states that feature PRs opened without a prior approved issue will be auto-closed, calling reviewer attention the scarcest resource. Bug fixes and non-overreaching performance improvements are accepted without prior discussion. That is a deliberate gate on behaviour changes, and it tells you the project is still settling its interfaces rather than freezing them.

The licence is the third thing to check. The repository metadata reports NOASSERTION rather than a recognised SPDX identifier, and LICENSE.md is the file to read. Nothing in the README or the workspace manifest resolves what terms apply, so treat the licence as unresolved until you have read that file.

Finally, this is not a general web host. If your service needs a single authoritative database, ordered writes, or a conventional request/response API with an SLA, the contract model is a mismatch, not a missing feature.

Freenet versus Hyphanet: two projects, one name

The search data around this project includes a comparison with Hyphanet, and the distinction matters because the two are different codebases with different architectures. Hyphanet is the older Freenet lineage, built around a datastore of published, mostly immutable content addressed by keys. freenet-core is a Rust workspace whose documented model is contracts holding application state, synchronized through summaries and deltas, with delegates for private state.

That is a difference in what the network stores and how it changes. A datastore of published content does not need a merge function, because content does not mutate in place; a contract that holds application state does, which is why the whitepaper's monoid requirement exists. The practical consequence is that a service built on freenet-core can update shared state without republishing, while the older model is oriented toward publishing and retrieving.

If you are choosing between them, the question is not which is better but which model matches your workload. State that changes and must converge across peers points at freenet-core. Content that is written once and read many times does not need the contract machinery at all. The README does not make this comparison, and the whitepaper is where the contract model is actually specified.

Maintenance, releases and what the licence leaves open

The repository is not archived, and the last push was on 2026-09-22. Releases land often: v0.2.134 on 2026-09-06, v0.2.135 on 2026-09-10, v0.2.136 on 2026-09-21. That cadence is the main signal about how the project is maintained, and it is a strong one. The README does not document a release process, a support window for older versions, or what changes are considered breaking between 0.2.x releases.

Upgrade cost therefore has to be estimated from the tree rather than from documentation. The workspace pins a Rust toolchain in rust-toolchain.toml and a Cargo.lock, so builds are reproducible from a checkout, but the README does not say whether a node can be upgraded in place or whether state formats are stable across releases. Before depending on a specific version, check the release notes for that version and the diff in the crates you use.

The licence is unresolved in what the repository states. Repository metadata reports NOASSERTION, which is not a licence grant, and LICENSE.md is the file that would settle it. If you plan to redistribute freenet-core or build a product on it, read LICENSE.md and, where the answer matters commercially, get your own legal advice. Nothing in the README states the terms.

What to verify before you commit

Three checks are worth doing before you build anything on freenet-core. First, confirm the build works on your toolchain with the pinned rust-toolchain.toml, since the README's only install instruction is cargo install --path crates/core and it does not list prerequisites. Second, read the whitepaper's contract section and decide whether your state can be expressed as an idempotent commutative merge; if it cannot, no amount of tooling will fix the mismatch. Third, read LICENSE.md, because the metadata does not state a licence.

After that, the practical path is the sample application. apps/freenet-ping is a complete small app with separated app, types and contract crates, and it is the only worked example in the tree. Copying its structure is more reliable than guessing from the core crates, because the README does not describe how an application is assembled.

What you should not expect is a documented operational story. There is no README section on running a peer, joining a network, or monitoring one. If your team needs that before adopting a platform, this repository does not provide it yet, and the frequent 0.2.x releases suggest the interfaces are still moving.

Editorial conclusion

Adopt freenet-core if you want to build against the contract and delegate model described in the whitepaper and are comfortable reading Rust source, since the README leaves the daily operation of a node undocumented. Do not adopt it if you need a stable, documented node operation guide, a supported Windows path, or a replacement for a conventional web application server. Before committing, verify that cargo install --path crates/core builds on your toolchain, that the components you need are present under crates/ and apps/, and that the whitepaper's contract model matches the state your application actually needs.

Frequently asked questions

Official sources

1. freenet/freenet-core on GitHub
2. Issues
3. Project website
4. README
5. Releases