Merge pull request #8 from Sam-Max/user-manual

Add user manual content with structured sections and table of contents

Author: sanity

.github/workflows/deploy.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v3
         with:
-          hugo-version: '0.133.1'
+          hugo-version: '0.141.0'
           extended: true
 
       # Setup Rust environment

hugo-site/content/_index.md

@@ -8,7 +8,7 @@ links:
     text: "Video Talks"
     icon: "fas fa-video"
     color: "is-medium-blue"
-  - url: "https://docs.freenet.org/"
+  - url: "/resources/manual/"
     text: "User Manual"
     icon: "fas fa-book"
     color: "is-medium-teal"

hugo-site/content/resources/manual/_index.md

@@ -0,0 +1,83 @@
+---
+title: "Freenet Manual"
+date: 2025-04-13
+draft: false
+layout: "single"
+---
+
+This guide provides **comprehensive documentation** on Freenet's components, architecture, and
+usage. Use the table of contents below to navigate through the manual.
+
+---
+
+## 📚 Table of Contents
+
+1. [Introduction](introduction)
+2. [Components](#components)
+3. [Architecture](#architecture)
+4. [Developer Guide](#developer-guide)
+5. [Examples](#examples)
+6. [Community and Support](#community-and-support)
+7. [Reference](#reference)
+
+---
+
+## 📝 Introduction
+
+Learn the basics of Freenet and its purpose.
+
+- [Introduction](introduction)
+
+---
+
+## Components
+
+Explore the key components of Freenet:
+
+- [Overview](components/overview): A high-level overview of Freenet's components.
+- [Contracts](components/contracts): Details about contracts in Freenet.
+- [Delegates](components/delegates): Explanation of delegates and their roles.
+- [User Interfaces](components/ui): Information on available user interfaces.
+
+---
+
+## 🏗️ Architecture {#architecture}
+
+Understand Freenet's architecture and how it works:
+
+- [P2P Network](architecture/p2p-network): Explore the peer-to-peer network structure.
+- [Intelligent Routing](architecture/irouting): Understand Freenet's intelligent routing mechanisms.
+- [Transport](architecture/transport): Learn about the transport layer in Freenet.
+
+---
+
+## 👩‍💻 Developer Guide {#developer-guide}
+
+Resources for developers working with Freenet:
+
+- [Tutorial: Create an App](tutorial): Step-by-step guide to creating an app on Freenet.
+- [Contract Interfaces](contract-interface): Reference for contract interfaces.
+- [Manifest Format](manifest): Details about the `freenet.toml` configuration format.
+
+---
+
+## 🛠️ Examples {#examples}
+
+- [Antiflood Tokens](examples/antiflood-tokens)
+- [Blind Trust Tokens](examples/blind-trust-tokens)
+
+---
+
+## 🌐 Community and Support {#community-and-support}
+
+Get involved with the Freenet community:
+
+- [Community](community)
+
+---
+
+## 📖 Reference {#reference}
+
+Additional resources and glossary:
+
+- [Glossary](glossary)

hugo-site/content/resources/manual/architecture/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Architecture"
+date: 2025-04-13
+draft: false
+---

hugo-site/content/resources/manual/architecture/irouting.md

@@ -0,0 +1,61 @@
+---
+title: "Intelligent Routing"
+date: 2025-04-13
+draft: false
+weight: 2
+---
+
+Freenet's request routing mechanism plays a crucial role in the efficiency of
+the network.
+
+It is responsible for deciding which peer to route a request to when attempting
+to read, create, or modify a contract's state. The mechanism is designed to
+select the peer that can complete the request the fastest, which may not always
+be the peer closest to the contract's location - the traditional approach for
+routing in a small-world network, known as [greedy
+routing](https://en.wikipedia.org/wiki/Small-world_routing#Greedy_routing).
+
+### Isotonic Regression
+
+Freenet uses [isotonic regression](https://github.com/sanity/pav.rs), a method
+for estimating a monotonically increasing or decreasing function given a set of
+data, to predict the response time from a peer based on its ring distance from
+the target location of the request.
+
+This estimation is then adjusted by the average difference between the isotonic
+regression estimate and the actual response time from previous interactions with
+the peer. This process enables a form of adaptive routing that selects the peer
+with the lowest estimated response time.
+
+### Router Initialization and Event Handling
+
+When a new
+[Router](https://github.com/freenet/freenet-core/blob/main/crates/core/src/router.rs)
+is created, it's initialized with a history of routing events. These events are
+processed to generate the initial state of the isotonic estimators. For example,
+failure outcomes and success durations are computed for each event in the
+history and used to initialize the respective estimators. The average transfer
+size is also computed from the history.
+
+The Router can add new events to its history, updating its estimators in the
+process. When a successful routing event occurs, the Router updates its response
+start time estimator, failure estimator, and transfer rate estimator based on
+the details of the event. If a failure occurs, only the failure estimator is
+updated.
+
+### Peer Selection
+
+To select a peer for routing a request, the Router first checks whether it has
+sufficient historical data. If not, it selects the peer with the minimum
+distance to the contract location. If it does have sufficient data, it predicts
+the outcome of routing the request to each available peer and selects the one
+with the best predicted outcome.
+
+### Outcome Prediction
+
+To predict the outcome of routing a request to a specific peer, the Router uses
+its isotonic estimators to predict the time to the start of the response, the
+chance of failure, and the transfer rate. These predictions are used to compute
+an expected total time for the request, with the cost of a failure being assumed
+as a multiple of the cost of success. The peer with the lowest expected total
+time is selected for routing the request.

hugo-site/content/resources/manual/architecture/p2p-network.md

@@ -0,0 +1,39 @@
+---
+title: "P2P Network"
+date: 2025-04-13
+draft: false
+---
+
+# Freenet Network Topology
+
+## Small-World Network
+
+Freenet is structured as a decentralized peer-to-peer network, based on the idea of
+a [small-world network](https://en.wikipedia.org/wiki/Small-world_network). This
+network topology is scalable and efficient, allowing contract state to be found
+quickly and without any reliance on a central authority.
+
+![Small World Network](/p2p-network.svg)
+
+## Freenet Peers
+
+In Freenet, a "peer" is any computer running the [Freenet
+Core](https://github.com/freenet/freenet-core) software. The peers are organized
+in a ring-like structure, with each peer assigned a specific numerical value
+between 0.0 and 1.0, indicating its location in the network's topology. This
+location is derived from the peer's IP address.
+
+## Establishing Neighbor Connections
+
+Every Freenet peer, also referred to as a node, forms two-way connections with a
+set of other peers, termed "neighbors." These connections utilize the User
+Datagram Protocol (UDP) and can do [Firewall hole punching](<https://en.wikipedia.org/wiki/Hole_punching_(networking)>) when necessary. Peers manage their resource usage —
+bandwidth, memory, CPU, and storage — based on limits set by the user.
+
+## Adaptive behavior
+
+Peers keep track of their neighbor's performance and learn to prefer faster
+connections over time.
+
+Peers can also identify bad behavior by other peers like excess resource usage and
+will disconnect from them.