WAIT — Mixed signals — read the receipts

• Last commit today
• 4 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 50% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Freenet-core is a peer-to-peer network runtime written in Rust that transforms user computers into a resilient, decentralized computing platform. It enables building fully interoperable decentralized applications (contracts) accessible via standard web browsers, solving the problem of internet dependency on centralized platforms by creating a global shared computer where services are always available through collective peer contribution. Monorepo structure: crates/core contains the main P2P runtime, crates/ holds additional modules (contract execution, network stacks, storage). apps/freenet-ping demonstrates application patterns with subdirs for contracts/ and types/. Tests spread across tests/ and inline (#[cfg(test)]). Heavy use of Tokio async patterns and custom protocol layers (transport.md, ring.md in .claude/rules indicate specialized subsystems).

Protocol engineers, decentralized systems developers, and P2P network researchers building censorship-resistant services; also application developers targeting the Freenet platform (see apps/freenet-ping for an example). Contributors need Rust expertise and understanding of distributed systems.

Actively maintained with strong CI/CD infrastructure (see .github/workflows/ci.yml, benchmarks.yml, cross-compile.yml). The codebase is substantial (~10.5M lines Rust) with comprehensive rule documentation in .claude/rules/. This is production-oriented code with established release workflows (release.yml) and cross-platform support (Cross.toml), though as a decentralized protocol it remains in evolution phase rather than stable 1.0.

High dependency count (tokio, axum, sqlx, redb, cryptographic libs) with frequent ecosystem changes; protocol-level changes risk node incompatibility. Complexity is significant: peer-to-peer networking, consensus, crypto, and contract execution require expertise. Submodule requirement (.gitmodule setup needed) and extensive rules documentation suggest active architectural decisions are being refined.

Active development visible in workflows: nightly simulations (simulation-nightly.yml), extended benchmarking (benchmarks-extended.yml), automated PR review (claude-pr-review.yml), and cross-platform compilation testing. The .claude/ rules and CLAUDE.md files indicate AI-assisted development is integrated into the workflow. Mirror syncing and e2e testing (macos-dmg-e2e.yml) suggest recent focus on platform stability.

git clone https://github.com/freenet/freenet-core
cd freenet-core
git submodule update --init --recursive
cargo install --path crates/core

Or for the fdev development utility: cargo install --path crates/fdev

Daily commands: No traditional 'dev server'; this is a network node runtime. Run cargo run --bin freenet (exact binary TBD from crates/) to start a node. For development: cargo test runs unit tests; cargo run --example <name> for demonstrations. Extended testing via nextest (.config/nextest.toml) for parallel execution. See workflows for integration test patterns.

• Cargo.toml — Workspace root manifest defining all member crates, dependencies, and feature flags that control the entire decentralized network stack.
• crates/core/Cargo.toml — Core runtime library manifest; defines transport, ring, contract execution, and node coordination—the foundation of Freenet's decentralized architecture.
• crates/core/architecture.md — Authoritative design documentation for the core node architecture, ring topology, transport layer, and contract system.
• .claude/rules — Engineering practices and code standards that all contributors must follow for consistency, safety, and deployment reliability.
• apps/freenet-ping/app/src/main.rs — Example application demonstrating how to build a decentralized app on Freenet; serves as reference for contract integration and messaging patterns.
• README.md — Project vision and onboarding entry point explaining Freenet's decentralization goals and core value proposition.
• .github/workflows/ci.yml — Continuous integration pipeline that validates all builds, tests, and deployments; critical for understanding PR requirements.

Create a new Freenet contract

1. Create a new contract crate using the ping contract as a template (apps/freenet-ping/contracts/ping/Cargo.toml)
2. Implement the contract logic in src/lib.rs with init, update, and summarize functions (apps/freenet-ping/contracts/ping/src/lib.rs)
3. Define the contract metadata including name, version, and hash (apps/freenet-ping/contracts/ping/freenet.toml)
4. Add integration test in the app tests directory to validate contract behavior (apps/freenet-ping/app/tests/run_app.rs)

Add a new network protocol or transport feature

1. Review transport architecture and safety rules (.claude/rules/transport.md)
2. Implement transport handler in core crate following LEDBAT patterns (crates/core/benches/transport/mod.rs)
3. Add benchmark tests to validate throughput, latency, and resource usage (crates/core/benches/transport_ci.rs)
4. Add integration test with multi-node simulation (apps/freenet-ping/app/tests/large_network_simulation.rs)

Build a new Freenet application using existing contracts

1. Create app crate following the freenet-ping structure (apps/freenet-ping/app/Cargo.toml)
2. Implement application main.rs using contract client patterns (apps/freenet-ping/app/src/main.rs)
3. Create shared types crate for contract interfaces (apps/freenet-ping/types/src/lib.rs)
4. Add e2e test demonstrating contract communication and state updates (apps/freenet-ping/app/tests/run_delegate_messaging_e2e.rs)

Extend ring topology or DHT behavior

1. Review ring consensus and topology rules (.claude/rules/ring.md)
2. Modify core ring implementation with new peer discovery or routing logic (crates/core/src)
3. Validate invariants using multi-node network simulation (apps/freenet-ping/app/tests/large_network_simulation.rs)
4. Update architecture documentation with new topology decisions (crates/core/architecture.md)

• Rust + WebAssembly — Rust provides memory safety and performance for the core network runtime; WebAssembly enables sandboxed, portable contract execution across heterogeneous nodes.
• DHT (Distributed Hash Table) Ring — Enables decentralized data location and retrieval without central indexing; peers cooperatively manage contract state partitions.
• LEDBAT Congestion Control — Allows efficient bandwidth sharing on consumer-grade connections by avoiding TCP congestion and minimizing latency impact on other users.
• Async/Tokio Runtime — Multiplexes thousands of peer connections and contract executions on limited OS threads, critical for node scalability.
• Delegates (Contract-to-Contract Messaging) — Enables contracts to collaborate and share state without exposing internal implementation, reducing coupling and enabling composable applications.

• Full decentralization with local contract execution

  • Why: Removes reliance on cloud providers and ensures user data privacy by default.
  • Consequence: Higher latency than centralized systems; requires more computational resources per node; eventual consistency rather than strong consistency.

• WebAssembly sandboxing over native code

  • Why: Ensures contracts cannot corrupt node runtime or escape to host OS; enables safe execution of untrusted contracts.
  • Consequence: Performance overhead of WASM interpretation (~30-50% slower than native); limited system call access; contract complexity constrained.

• Gossip-based state propagation vs. centralized consensus

  • Why: Avoids single point of failure and enables operation across unreliable/intermittent networks.
  • Consequence: Eventual consistency model; temporary partition inconsistency; higher bandwidth overhead for duplicate state replication.

• Client-side contract state validation

  • Why: Distributes validation work across the network and prevents node overload from malicious contracts.
  • Consequence: Requires nodes to store contract logic; network must reach consensus on validation rules; complex debugging.

• Does not provide real-time guarantees; designed for eventual consistency and intermittent connectivity.
• Does not handle traditional SQL relational queries; contracts manage their own state schema.
• Not a blockchain; uses off-chain contract execution and DHT storage rather than on-chain ledgers.
• Does not provide anonymous communication; relies on IP-based P2P networking (use Tor/VPN overlay if anonymity required).
• Not a replacement for DNS or certificate authorities; no built-in identity/PKI system.
• Does not support rich-media streaming at broadcast scale; designed for collaborative applications, not CDN.

Must run git submodule update --init --recursive before any build (submodules contain protocol/contract definitions). Cargo workspace uses resolver = '2' (required for monorepo coherence). Tests may require local tokio runtime setup; see .config/nextest.toml for parallel test execution quirks. Cross-platform testing (Cross.toml) requires Docker. Rule files in .claude/ are part of the codebase contract—deviations may break CI (claude.yml workflow enforces these). Crypto operations with zeroize require careful memory handling (no copies of secrets).

• Distributed Hash Table (DHT) / Ring Topology — Freenet's peer discovery and routing mechanism (documented in .claude/rules/ring.md) determines how nodes find each other and forward messages efficiently across the network
• Smart Contracts / Contracts Model — Applications on Freenet are defined as contracts (see .claude/rules/contracts.md and apps/freenet-ping/); understanding the execution model and state transitions is essential for building apps
• Async/Await & Tokio Runtime — Entire codebase is built on Tokio; understanding cooperative multitasking, futures, and channel-based communication is mandatory for any modification to the core runtime
• Cryptographic Key Exchange (x25519) & AEAD Encryption (AES-GCM, ChaCha20-Poly1305) — Peer-to-peer communication is encrypted; these primitives (x25519-dalek, aes-gcm, chacha20poly1305 in Cargo.toml) secure channels and require understanding of modern crypto practices
• Flatbuffers Serialization — Protocol messages use flatbuffers for schema-driven serialization (more efficient than JSON/bincode for P2P); essential for understanding inter-node communication and contract data formats
• Content-Addressed Storage & Hashing (BLAKE3) — Services and contracts are likely identified and verified via cryptographic hashes (blake3 in dependencies); understanding content addressing is crucial for contract deployment and versioning
• Channel Safety & Message Passing Patterns — Extensive rules in .claude/rules/channel-safety.md indicate careful handling of Tokio channels to prevent deadlocks; this is critical for P2P systems where message ordering and backpressure matter

• libp2p/rust-libp2p — Alternative P2P networking stack; Freenet uses custom transport but developers may compare modular networking approaches
• near/nearcore — Comparable Rust-based decentralized runtime for contract execution; useful reference for state management and sharding patterns
• ipfs/go-ipfs — Complementary content-addressing system; Freenet focuses on compute/service distribution while IPFS handles distributed storage
• freenet/freenet-core-docs — Official documentation repository (if separate) containing protocol specifications and developer guides for the network
• freenet/freenet-web — Web interface and browser integration layer allowing users to access Freenet services through standard HTTP APIs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for channel-safety rules in transport layer

The repo has .claude/rules/channel-safety.md documenting critical transport security patterns, but there are no dedicated integration tests validating these rules are enforced. The transport layer is mission-critical for a decentralized network. Adding tests would verify that channel-safety constraints are properly implemented across crates/freenet-core transport modules, catching regressions early.

• [ ] Review .claude/rules/channel-safety.md to identify testable safety invariants
• [ ] Create crates/freenet-core/tests/channel_safety_integration.rs with tests for encryption, authentication, and connection validation
• [ ] Add test cases for the scenarios documented in ring.md and transport.md rules
• [ ] Integrate into CI workflow by adding test target to .github/workflows/ci.yml

Implement contract deployment validation tests based on deployment rules

The .claude/rules/deployment.md file exists outlining deployment constraints, but there are no specific tests in tests/test-contract-* directories validating deployment safety checks. With multiple test contracts already present (test-contract-integration, test-contract-update-nochange, test-contract-mock-aligned), adding deployment validation tests would ensure contracts follow the documented deployment rules before they reach production.

• [ ] Read .claude/rules/deployment.md to extract deployment validation requirements
• [ ] Create tests/test-contract-deployment-validation/src/lib.rs with contract deployment verification tests
• [ ] Add tests for versioning, state transitions, and dependency constraints
• [ ] Update workspace Cargo.toml to include the new test crate and add to CI workflow

Add simulation-based performance benchmarks for ring topology operations

The repo has .claude/rules/ring.md documenting ring topology constraints and .github/workflows/simulation-nightly.yml for extended simulations, but there are no explicit benchmarks measuring ring operation performance (node joining, message routing latency). Given the existing simulation infrastructure and freenet-ping app tests, adding ring-specific benchmarks would help catch performance regressions in the DHT topology layer.

• [ ] Review .claude/rules/ring.md and existing simulation tests in apps/freenet-ping/app/tests/test_*_network_*.rs
• [ ] Create crates/freenet-core/benches/ring_operations.rs with benchmarks for node join/leave and message routing
• [ ] Extend .github/workflows/benchmarks.yml to include ring topology benchmarks with baseline comparisons
• [ ] Document expected performance characteristics in a new docs/ring-performance.md guide

• Add missing integration tests for the WebSocket transport layer (tokio-tungstenite) in crates/core; protocol.md documents the message format but coverage gaps likely exist
• Expand documentation in .claude/rules/operations.md with concrete examples of node lifecycle management (startup, shutdown, peer discovery) using code from crates/core
• Write E2E tests for contract deployment and execution using the freenet-ping example; structure should follow macos-dmg-e2e.yml pattern but be OS-agnostic

• High · Incomplete Dependency List in Workspace — Cargo.toml - workspace.dependencies section. The Cargo.toml workspace dependencies list appears truncated (ends abruptly at 'opentelemetr'). This prevents complete analysis of all dependencies for known vulnerabilities. The observability/tracing dependencies are incomplete, which could include unvetted or vulnerable versions. Fix: Complete the dependency declarations and run 'cargo audit' to identify any known vulnerabilities in dependencies. Ensure all transitive dependencies are reviewed.
• High · Use of Outdated/Potentially Vulnerable Crypto Dependencies — Cargo.toml - crypto dependencies (aes-gcm, blake3, x25519-dalek, chacha20poly1305, sha2). The codebase uses older versions of cryptographic libraries: x25519-dalek 2.x (should consider 2.1+ for latest security patches), and no explicit version constraint on blake3. Cryptographic libraries require frequent updates for security patches. Fix: Review crypto dependency versions against RUSTSEC database. Pin to latest patch versions and establish a process for regular security updates. Consider using 'cargo audit' in CI/CD pipeline.
• Medium · SQL Injection Risk via sqlx — Cargo.toml - sqlx dependency; likely in crates/core data layer. The codebase includes sqlx with SQLite support. While sqlx provides compile-time query checking, the presence of dynamic SQL query construction patterns (common in Rust persistence layers) could lead to SQL injection if not properly parameterized. Fix: Audit all SQL queries to ensure parameterized queries are used exclusively. Enable sqlx compile-time checking for all queries. Document SQL safety requirements in code review guidelines.
• Medium · Deserialization Without Validation — Cargo.toml - serde, bincode, flatbuffers; implementation files unknown without code inspection. Multiple serialization libraries (serde, bincode, flatbuffers) are included without evidence of strict input validation. Deserializing untrusted data could lead to denial of service or arbitrary code execution in certain contexts. Fix: Implement strict schema validation for all deserialized data. Use serde's 'deny_unknown_fields' and custom validators. Add fuzzing tests for deserialization with untrusted input.
• Medium · Permissive Default TLS Configuration — Cargo.toml - reqwest dependency; likely in network communication layer. reqwest is configured with 'rustls-tls' but no explicit certificate validation strategy is visible. Network communications in a decentralized system require strict TLS validation to prevent MITM attacks. Fix: Explicitly configure certificate validation and pinning where applicable. Review all HTTP client initialization code. Consider implementing certificate transparency validation for critical connections.
• Medium · Insufficient Secrets Management — .github/workflows/, .githooks/, configuration files. While a .gitignore file exists, there is no evidence of explicit secrets management strategy. Hardcoded configuration in git hooks (.githooks/commit-msg) and CI/CD workflows (.github/workflows) could inadvertently commit secrets. Fix: Implement pre-commit hooks to detect and prevent secrets from being committed. Use GitHub Secrets for sensitive values in workflows. Audit all config files for hardcoded credentials.
• Medium · Weak Randomness Configuration — Cargo.toml - rand dependency. The rand crate is included with default configuration. In a cryptographic context (which freenet-core is), rand MUST use cryptographically secure RNG. Default rand may not be sufficient for cryptographic operations. Fix: Verify that rand is only used for non-cryptographic purposes. For cryptographic randomness, use rand::rngs::OsRng or x25519-dalek's built-in RNG. Add documentation and code review guidelines.
• Low · Missing SBOM and Dependency Tracking — Repository root - missing cargo-sbom or similar tooling. No evidence of Software Bill of Materials (SBOM) generation or dependency tracking automation. This complicates vulnerability response and supply chain security. Fix: Integrate cargo-sbom or similar tools into CI/CD. Generate and maintain SBOMs for releases. Consider enabling Dependabot (currently has dependabot.yml but audit.yml

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/freenet/freenet-core shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live freenet/freenet-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/freenet/freenet-core.

What it runs against: a local clone of freenet/freenet-core — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in freenet/freenet-core | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of freenet/freenet-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/freenet/freenet-core.git
#   cd freenet-core
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of freenet/freenet-core and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "freenet/freenet-core(\\.git)?\\b" \\
  && ok "origin remote is freenet/freenet-core" \\
  || miss "origin remote is not freenet/freenet-core (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/core/Cargo.toml" \\
  && ok "crates/core/Cargo.toml" \\
  || miss "missing critical file: crates/core/Cargo.toml"
test -f "crates/core/architecture.md" \\
  && ok "crates/core/architecture.md" \\
  || miss "missing critical file: crates/core/architecture.md"
test -f ".claude/rules" \\
  && ok ".claude/rules" \\
  || miss "missing critical file: .claude/rules"
test -f "apps/freenet-ping/app/src/main.rs" \\
  && ok "apps/freenet-ping/app/src/main.rs" \\
  || miss "missing critical file: apps/freenet-ping/app/src/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/freenet/freenet-core"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.