About Freenet
Contents
Introduction
Freenet is a distributed, decentralized alternative to the centralized World Wide Web, designed to unleash a new era of innovation and competition, while protecting freedom of speech and privacy.
At the core of Freenet is a small piece of software known as the Freenet kernel, which runs on users' computers, smartphones, or other devices. The kernel is tiny, less than 5 MB, allowing it to be installed in a matter of seconds and is compatible with a wide range of hardware.
Freenet is a peer-to-peer network, which means that nodes self-organize into a global network without any central authority, and the work of hosting services is distributed among the users.
This user manual is primarily intended for developers who wish to build decentralized software systems on the Freenet platform.
Building Decentralized Applications on Freenet
Delegates, contracts, and user interfaces (UIs) each serve distinct roles in the Freenet ecosystem. Contracts control public data, or "shared state". Delegates act as the user's agent and can store private data on the user's behalf, while UIs provide an interface between these and the user through a web browser. UIs are distributed through the P2P network via contracts.
Freenet Kernel
The kernel is the core of Freenet, it's the software that runs on the user's computer. It's responsible for:
- Providing a user-friendly interface to access Freenet via a web browser
- Host the user's delegates and the private data they store
- Host contracts and their associated data on behalf of the network
- Manage communication between contracts, delegates, and UI components
The kernel is written in Rust and is designed to be small (hopefully less than 5 MB), efficient, and able to run on a wide range of devices like smartphones, desktop computers, and embedded devices. can
User Interface
On the normal web, a user might visit https://gmail.com/, their browser will download the Gmail user interface which then runs in their browser and connects back to the Gmail servers.
On Freenet the user interface is downloaded from a Freenet contract, and it interacts with contracts and delegates through the Freenet kernel.
These UIs are built using web technologies such as HTML, CSS, and JavaScript, and are distributed over Freenet and run in a web browser. UIs can create, retrieve, and update contracts through a WebSocket connection to the local Freenet peer, as well as communicate with delegates.
Because UIs run in a web browser, they can be built using any web framework, such as React, Angular, Vue.js, Bootstrap, and so on.
Contracts
Contracts in Freenet are WebAssembly components that manage and regulate public state. They can be likened to inodes in a filesystem, tables in a database, or memory locations in a globally shared memory. Contracts define the circumstances under which state can be modified and whether a given state is allowed.
Contracts and their associated state reside on the Freenet network on peers determined by the contract's location, which is derived from its WebAssembly code and parameters. While a user's delegates are hosted on their local Freenet peer, contracts are hosted on the network as a whole.
Contracts also outline how to merge two valid states, creating a new state that incorporates both. This process ensures eventual consistency of the state in Freenet, using an approach akin to CRDTs. The contract defines a commutative monoid on the contract's state.
Each contract is identified by a cryptographic hash, which is a combination of its code and parameters, also referred to as its "key". This key is used to identify the contract and to verify that the contract's code and parameters have not been tampered with.
Contract Use Cases
Take, for example, a public blog contract. The state of this contract would be the blog's content, which consists of a list of blog posts. The code within the contract dictates that new posts may only be added if they are signed by the blog's owner, while the contract's parameters include the blog owner's public key.
Delegates
Delegates are WebAssembly code that act as user avatars on Freenet, they must implement the DelegateInterface.
Delegates run in the Freenet kernel and manage private data and interact with other Freenet entities like contracts, apps, and other delegates on behalf of the user. They can store and control private data like cryptographic keys, tokens, and passwords, and communicate with users, for example to ask permission to sign some data. They can be created by UI components or other delegates.
Unlike contracts, which require network verification, delegates run on the user's computer and are trusted to execute code without verification. Delegates' state is private, while contracts' state is public but may be encrypted.
Delegates are used for:
- Managing private data similar to a browser's web storage
- eg. private keys, tokens
- Acting on the user's behalf on Freenet
- eg. consuming received messages in an inbox
- Storing user data
- e.g., contacts, messages
Origin Attestation
Delegates communicate with apps and other delegates using messages, a crucial aspect of which is the delegate's ability to identify the origin of a message. The origin is identified by the key associated with the app, contract, or other delegate that sent the message. This key is generated cryptographically based on the code and configuration parameters of the sender, enabling delegates to verify the behavior of other delegates or apps with which they interact.
This allows for highly flexible composability, as components can trust the behavior of the components they communicate with by verifying their code and configuration parameters.
Delegate Use Cases
-
A key manager delegate is responsible for managing a user's private keys, other components can request that the key manager delegate sign messages or other data on their behalf.
-
An inbox delegate is responsible for maintaining an inbox of messages sent to the user in a messaging system. It pulls messages from an inbox contract, decrypts them, and stores them locally where they can be queried by other components.
Freenet Network Topology
Small-World Network
Freenet operates as a decentralized peer-to-peer network based on the principles of a small-world network. This network topology allows Freenet to be resilient against denial-of-service attacks, automatically scale to accommodate demand, and provide observable data stores. Users can subscribe to specific keys to receive notifications of updates as they occur.
Understanding Freenet Peers
A Freenet peer refers to a computer that runs the Freenet kernel software and participates in the network. The organization of peers follows a ring structure, where each position on the ring represents a numerical value ranging from 0.0 to 1.0. This value signifies the peer's location within the network.
Establishing Neighbor Connections
Each Freenet peer, or kernel, establishes bi-directional connections with a group of other peers known as its "neighbors." These connections rely on the User Datagram Protocol (UDP) and may involve techniques to traverse firewalls when required.
To optimize resource utilization, peers monitor the resources they use while responding to neighbor requests, including bandwidth, memory, CPU usage, and storage. Peers also track the services offered by their neighbors, measured by the number of requests directed to those neighbors.
To ensure network efficiency, a peer may sever its connection with a neighbor that consumes excessive resources relative to the number of requests it receives.
Implementing Adaptive Routing for Efficient Data Retrieval
When a peer intends to read, create, or modify a contract, it sends a request to the peers hosting the contract. The request is directed to the neighbor most likely to retrieve the contract quickly. Ideally, this neighbor is the one closest to the contract's location, a concept known as "greedy routing." However, other factors, such as connection speed, may influence the selection.
Freenet addresses this challenge by monitoring the past performance of peers and selecting the one most likely to respond quickly and successfully. This selection considers both past performance and proximity to the desired contract. The process, known as adaptive routing, employs an algorithm called isotonic regression.