diff --git a/docs/assets/ONLIFE ART 1.png b/docs/assets/ONLIFE ART 1.png new file mode 100644 index 0000000..caef0ea Binary files /dev/null and b/docs/assets/ONLIFE ART 1.png differ diff --git a/docs/assets/diagrams/topology.png b/docs/assets/diagrams/topology.png new file mode 100644 index 0000000..ed2b098 Binary files /dev/null and b/docs/assets/diagrams/topology.png differ diff --git a/docs/smartup-zero/design-blueprint.md b/docs/smartup-zero/design-blueprint.md new file mode 100644 index 0000000..709f105 --- /dev/null +++ b/docs/smartup-zero/design-blueprint.md @@ -0,0 +1,71 @@ +# :material-palette: 2. Design Blueprint + +!!! info "What is this section?" + This document is the official **Design Blueprint** for Smartup Zero's ONLIFE project. It defines the user experience (UX) principles for **Deckpack**, the citizen's 'browser' for the Onlife network. It is the primary responsibility of the **`3_2_design_team`**. + + - **Attacker (A):** The members of the `3_2_design_team` are the "attackers" who research, design, and propose the user experience. + - **Defender (D):** The `4_1_2_tc_design_team` (the Team Captain) is the "defender," responsible for reviewing designs and ensuring they align with our core principles. + - **Midfielder (M):** The `Engelbot` is the "midfielder," which automates the process of publishing the approved version of this document to the `0_timeline.org` website. + +## 1. Mission Summary + +Our mission is to design Deckpack as a generic and resilient "Operating System" for crisis situations, empowering citizens and organizations to build and deploy their own tools on the Onlife network. + +## 2. Main Part: The Deckpack Platform Design + +Deckpack is not a single-purpose app; it is a platform. Its design is based on a generic, powerful, and adaptable model that can be configured for any type of emergency. The core of this design rests on three fundamental elements: **Groups, Plugins, and Cards**. + +### 2.1. The Three Core UX Elements + +#### 2.1.1. Groups: The Shared Computer +A `Group` is a temporary, ad-hoc network formed by a cluster of smartphones running Deckpack in the same physical area. It is, in effect, a shared, decentralized "computer" that exists only as long as the devices are near each other. We define two types of groups: + +| Group Type | Description | Host | MVP Focus? | +| :--- | :--- | :--- | :--- | +| **Onlife Group** | The default, public group that forms automatically. Anyone in range can join. It contains a set of essential, pre-loaded emergency plugins. | "Hosted by nobody" - it is self-forming. | **Yes, this is the core of the MVP.** | +| **Context Group**| A private group created by a specific citizen or organization for a specific purpose (e.g., a "Red Cross Team" group). | Hosted by its creator. | No, this is a future capability. | + +#### 2.1.2. Plugins: The Emergency Software +`Plugins` are the applications that provide functionality within a `Group`. They are the "software" that runs on the shared "computer." They define the actions a citizen can take. For the MVP, Smartup Zero will create a basic set of emergency plugins. In the future, our SDK will allow trusted partners (like NGOs and local governments) to develop and deploy their own `Plugins` for specific crises. + +#### 2.1.3. Cards: The Citizen's Files +`Cards` are the tangible, digital objects that citizens interact with. They are like the "files" on a computer. A citizen uses a `Plugin` to create a `Card`, which is then shared with the `Group`. For example, a "Broadcast Message" `Plugin` would create a "Message" `Card`. The design of these interactions is inspired by the simple, universally understood dynamics of a card game (playing, saving, discarding), but this is a design hypothesis to be validated by the team. + +### 2.2. Use Case Example: The MVP in Action +Now, let's see how these generic elements work together in a real-world MVP scenario. + +**Scenario:** A massive earthquake has hit Istanbul. Power is out, and cellular networks are down. + +1. **Forming the Group:** A citizen, Ayse, opens Deckpack. The app automatically discovers other nearby users and connects them, forming a public **Onlife Group** for her immediate neighborhood. +2. **Using a Plugin:** The `Onlife Group` comes pre-loaded with a basic **SOS Plugin**. Ayse taps the "I Need Help" button to activate it. +3. **Creating a Card:** The `SOS Plugin` presents Ayse with a simple interface. She selects "Medical" for her injured neighbor. The plugin bundles this information with her location into a new **SOS Card**. +4. **Sharing the Card:** Ayse "plays" her `SOS Card` to the group's shared "Stage." Everyone else in the `Onlife Group` can now see this card, showing a need for medical help at her location. +5. **Coordination:** A Red Cross worker moving through the area also joins the local `Onlife Group`. She uses a special **Responder Plugin** that aggregates all the active `SOS Cards` onto a map, allowing her to coordinate an effective response. + +In this example, the Deckpack platform did not need to know what an "earthquake" was. It simply provided the environment (`Group`), the tools (`Plugins`), and the interface (`Cards`) for citizens and responders to coordinate. + +## 3. Submissions: The Design Roadmap +To design this platform and its inaugural MVP, the team will complete the following submissions. + +| Objective ID | Submission Title | Core Goal | Status | +| :--- | :--- | :--- | :--- | +| `5_1_2_2...` | **Design the Core Deckpack Environment** | To create the wireframes and UI for the generic platform: group discovery, the `Stage`, and the `Hand`. | :material-calendar: Planned | +| `5_2_2_2...` | **Design the "First Response" MVP Pack** | To create the high-fidelity, validated designs for the essential `SOS` and `Aid` plugins and the `Cards` they produce. | :material-calendar: Planned | +| `5_3_2_2...` | **Define the Plugin SDK Design Guidelines** | To create the initial design specifications and UI kit that future partners will use to build their own `Plugins`. | :material-calendar: Planned | + +## 4. Role Management: Call for Contributions +To design a platform of this ambition, we need designers who can think in systems. + +| Role ID | Role Title | Your Mission If You Join | +| :--- | :--- | :--- | +| `4_1_2` | **Platform UX Designer** | You will design the core, generic Deckpack experience, ensuring it is a simple and powerful foundation for any plugin. | +| `4_2_2` | **Crisis Interaction Designer** | You will focus on the MVP "First Response Plugin Pack," ensuring the experience of sending an SOS is foolproof under extreme stress. | +| `4_3_2` | **SDK/Partner Experience Designer**| You will design the SDK guidelines and UI kit, creating an amazing experience for our partners like the Red Cross to build their own tools. | + +## 5. Team Budget + +| Item | Value (SC) | Status | +| :--- | :--- | :--- | +| **Total Phase 1 Budget:** | 0 | Awaiting initial crowdfunding | +| **SC Minted to Date:** | 0 | - | +| **Remaining Budget:** | 0 | Our first goal is to meet the Validation Phase crowdfunding target. | diff --git a/docs/smartup-zero/development-blueprint.md b/docs/smartup-zero/development-blueprint.md new file mode 100644 index 0000000..ec38854 --- /dev/null +++ b/docs/smartup-zero/development-blueprint.md @@ -0,0 +1,98 @@ +# :material-hammer: 3. Development Blueprint + +!!! info "What is this section?" + This document is the official **Development Blueprint** for Smartup Zero's ONLIFE project. It outlines the technical plan for building **Deckpack**, the first application ('browser') for the Onlife network. It is the primary responsibility of the **`3_3_development_team`**. + + - **Attacker (A):** The members of the `3_3_development_team` are the "attackers" who build the application and propose the technical solutions. + - **Defender (D):** The `4_1_3_tc_development_team` (the Team Captain) is the "defender," responsible for code reviews and ensuring the implementation aligns with the Science and Design blueprints. + - **Midfielder (M):** The `Engelbot` is the "midfielder," automating builds, tests, and deployments. + +## 1. Mission Summary + +Our mission is to build the first stable, secure, and cross-platform version of Deckpack, successfully implementing the Onlife protocol to create a functional lifeline for citizens in emergencies. + +## 2. Main Part: The Deckpack Application Architecture + +Deckpack is the application layer that makes the Onlife network's power accessible. While the **Science Blueprint** defines the protocol theory, this document defines how we will *implement* that theory in a functional mobile application. + +### 2.1. The Deckpack Application: The First "Browser" for Onlife +Deckpack is a mobile app that allows groups of people in a disaster area or communication blackout to form temporary, self-sustaining networks. Within these secure `Groups`, citizens can use crisis-specific tools (`Plugins`) to share vital information (`Cards`). + +The development focus is on creating a modular and scalable architecture that can be extended by our partners in the future, while ensuring the initial MVP is robust and reliable for its core life-saving mission. + +### 2.2. MVP App Architecture Principles +The application will be built on three core architectural principles: + +1. **Protocol-Centric:** The app's primary function is to be a faithful and efficient implementation of the **Onlife Mesh Protocol** as defined in the Science Blueprint. All networking logic will be handled by a dedicated, sandboxed service layer that runs the UDP-based protocol. +2. **Modular & Scalable:** The architecture will clearly separate the core protocol service from the UI and the `Plugin` framework. This allows us to update the UI without touching the network code, and allows new plugins to be added without destabilizing the core application. +3. **Cross-Platform by Design:** While the initial MVP will likely target Android due to its hardware accessibility, the architecture will be designed with iOS compatibility in mind from day one, using clean interfaces between the protocol layer and the platform-specific UI. + +```mermaid +graph TD + subgraph Smartphone + A[Hardware - Wi-Fi] + B[Operating System - Android/iOS] + C[Deckpack Application] + D[Onlife Protocol Service] + end + + C -- "Talks to" --> D + D -- "Controls" --> A + C -- "Runs on" --> B + B -- "Manages" --> A +``` +*Figure: The relationship between the Deckpack App, the Onlife Protocol Service, and the underlying device hardware.* + +### 2.3. Core Components to Be Built +The development work is broken down into these key functional components: + +#### Group Management +The app must manage a citizen's membership in local `Groups`. +- **Discovery:** Implement the network scanning logic from the Science Blueprint to find nearby `Onlife Groups` by matching the predefined SSID pattern. +- **Connection:** Build the connection logic that allows a user to securely join a `Group`. +- **Host Functions:** For the MVP, the "Group Host" is abstract. The core app must simply connect to the default, public `Onlife Group`. The framework for third-party `Context Groups` will be built in a later version. + +#### Plugin Framework (SDK) +This is a critical component for long-term success. +- **Plugin Loader:** Develop a mechanism to automatically discover and install the `Plugins` that are designated for a specific `Group`. +- **Sandboxed Environment:** Ensure plugins run in a secure, isolated context. They must not have access to the core protocol service or data from other plugins unless explicitly permitted. +- **API Definition:** Create the clear API that allows a `Plugin` to request network actions (like creating and publishing a `Card`) from the core Deckpack application. + +#### Card-Based Interactions +The Development Team will build the UI systems to support the "Card Game" metaphor from the Design Blueprint. +- **Card Renderer:** Create a flexible UI component that can display different types of `Cards` based on the data provided by a `Plugin`. +- **Interaction Logic:** Implement the `Hand` and `Stage` concepts, allowing a user to manage their private cards and view the shared, public cards of the group. +- **Gesture Engine:** Build the gesture handlers (swipe up, down, left, right) for interacting with cards, as defined by the Design Team. + +#### Security & Data Control +Security is not a feature; it is a foundational requirement. +- **Encryption:** While the Onlife protocol is insecure by design, the Deckpack application **must** ensure that all sensitive `Card` data is end-to-end encrypted before it is passed to the protocol layer for transmission. +- **Secure Storage:** User-generated `Cards` and private keys must be stored in the device's most secure storage (e.g., Android Keystore). +- **Permissions:** A `Plugin` must explicitly declare what data and permissions it needs, and the user must grant consent. + +## 3. Submissions: The Development Roadmap +To build the MVP, we will complete the following major technical submissions. + +| Objective ID | Submission Title | Core Goal | Status | +| :--- | :--- | :--- | :--- | +| `5_1_3_3...` | **Build the Core Protocol Service** | To create a stable, background Android service that successfully implements the Onlife protocol for discovering and connecting to nodes. | :material-calendar: Planned | +| `5_2_3_3...` | **Build the MVP Application Shell** | To develop the basic Deckpack UI, including the `Group` discovery screen, the shared `Stage`, and the private `Hand`. | :material-calendar: Planned | +| `5_3_3_3...` | **Implement the First Plugin Pack** | To integrate the `SOS` and `Aid` plugins, allowing users to create, publish, and view live `SOS` and `Aid` cards on the network. | :material-calendar: Planned | + +## 4. Role Management: Call for Contributions +To build a platform of this complexity, we need a diverse and skilled development team. + +| Role ID | Role Title | Your Mission If You Join | +| :--- | :--- | :--- | +| `4_4_3` | **Android Developer** | You will build the core Deckpack application shell and UI components in Kotlin, bringing the design to life. | +| `4_6_3` | **iOS Developer** | You will lead the effort to port the Deckpack architecture and Onlife service to the iOS platform, ensuring we can reach all citizens. | +| `4_10_3` | **Network Protocol Engineer** | You will specialize in the low-level implementation of the Onlife protocol, optimizing routing, connection, and discovery. | +| `4_5_3` | **QA & Test Engineer** | You will build the automated testing suites that simulate network chaos to ensure Deckpack is truly resilient when it's needed most. | + +## 5. Team Budget + +| Item | Value (SC) | Status | +| :--- | :--- | :--- | +| **Total Phase 1 Budget:** | 0 | Awaiting initial crowdfunding | +| **SC Minted to Date:** | 0 | - | +| **Remaining Budget:** | 0 | Our first goal is to meet the Validation Phase crowdfunding target. | diff --git a/docs/smartup-zero/one-pager.md b/docs/smartup-zero/one-pager.md index f061362..bce6c7d 100644 --- a/docs/smartup-zero/one-pager.md +++ b/docs/smartup-zero/one-pager.md @@ -3,6 +3,9 @@ !!! abstract "Building ONLIFE - Europe's Emergency Communication Infrastructure" ONLIFE is a citizen protection initiative developing a smartphone-based emergency network that works without internet or telecoms. In times of cyberattacks, large-scale disruptions, or disasters, citizens continue communicating via a decentralized mesh network using existing smartphone hardware. As Smartup Zero's inaugural project, ONLIFE aims to become a strategic cornerstone of the EU Readiness 2030 program. +![Centered image](../assets/ONLIFE ART 1.png){ style="display: block; margin: 0 auto; width: 500px;" } + + ## :material-format-list-numbered: Business Plan Structure
diff --git a/docs/smartup-zero/science-blueprint.md b/docs/smartup-zero/science-blueprint.md new file mode 100644 index 0000000..78062f1 --- /dev/null +++ b/docs/smartup-zero/science-blueprint.md @@ -0,0 +1,447 @@ +# :material-flask: 6. Science Blueprint + +!!! info "What is this section?" + This document is the official Science Blueprint for Smartup Zero's Onlife project. It is the foundational scientific specification for the Onlife mesh protocol, serving as the single source of truth for its architecture, logic, and behavior. It is the primary responsibility of the 3_6_science_team. + - **Attacker (A):** The members of the `3_6_science_team` are the "attackers" who research, define, and propose the protocol's logic. + - **Defender (D):** The `4_1_6_tc_science_team` (the Team Captain) and external academic peers are the "defenders," responsible for reviewing and validating the scientific soundness of this blueprint. + - **Midfielder (M):** The `Engelbot` is the "midfielder," which automates the process of publishing the approved version of this document to the `0_timeline.org` website. + +## 1. Mission Summary + +Our mission is to define, validate, and evolve a secure, scalable, and resilient emergency mesh network protocol that can function on standard smartphones without special hardware or device modification. + +## 2. Main Part: The Onlife Mesh Protocol v0.1 + +This section provides a thorough technical understanding of the Onlife mesh protocol solution. + +### 2.1. Introduction + +Project Onlife aims to provide mesh functionality to smartphones using Android 12+, without the need for rooting the devices. The aim is to leverage the **AP/STA concurrency** of modern smartphones in order to build a mesh without the need for external hardware. + +#### Engineering Challenges +To achieve this goal, several challenges must be overcome. These challenges include, but are not limited to: + +- **Hardware Exclusivity:** The network is made up exclusively of smartphones (nodes) without the need for extra hardware. This is challenging due to the difficulty of managing mobile, disconnecting access points. +- **Node Mobility:** The network nodes are not static and move over time. The design must reflect the capability to rapidly morph and update as nodes enter, leave, and move within the network. +- **Reliable Packet Transport:** The network must have a reliable mechanism to ensure data sent from a node A arrives at its intended destination, node B. +- **Ungraceful Disconnects:** Nodes can suddenly disconnect due to range, battery, or operator termination. The network must be able to recover from these sudden failures. +- **Rapid Re-connection:** As nodes move, new optimal connection paths must be established quickly, while old, degraded connections are abandoned. + +Considering all engineering challenges, a solution is proposed using hardware and capabilities available on Android smartphones launched after January 2023. + +### 2.2. Motivation + +This document describes the proposed mesh network protocol for Onlife. The protocol is specifically designed to be implemented on unrooted smartphones. The aim of the protocol is to provide a scalable, low-data-traffic solution for mesh networking on smartphones. + +This protocol describes a means of creating such a network specifically aimed to be scalable up to a minimum of 75 nodes, using data caching for fast content delivery over larger networks, and be capable of handling the ever-changing nature of a network with moving connections. + +### 2.3. List of Definitions + +| Term | Definition | +| :--- | :--- | +| **Ack message** | A message used to acknowledge something. | +| **AP or Access point** | A device used to connect clients to a network. | +| **AP interface** | The network interface responsible for providing access point capabilities. | +| **Child node** | A node directly connected to a parent node. The relationship is always relative. | +| **Client network** | The network set up by each distribution node to serve data to clients. | +| **Data Manifest** | A table used to store UUIDs and IP addresses of network-accessible content. | +| **Distribution network** | The network that links the distribution nodes together, providing connectivity to the entire mesh. | +| **Local data Manifest**| A table used by a distribution node to provide NAT capabilities by coupling UUIDs to NAT identifiers. | +| **NAT** | Network Address Translation, a method to serve multiple devices using a single public IP. | +| **Network plane** | A single layer within the network topology model. | +| **Nodes** | Network-capable devices that are part of the network. | +| **Parent node** | A node acting as the connection point for its directly connected child node. | +| **Root plane** | The topmost layer of the topology model. | +| **RSSI** | A metric to describe the connection strength of a Wi-Fi network. | +| **STA/AP concurrency** | A mode where a Wi-Fi device can simultaneously be a client (STA) and an Access Point (AP). | +| **STA interface** | The station interface responsible for connecting to a Wi-Fi network. | +| **SSID** | The broadcasted network name used for identification. | +| **Throughput** | The amount of data a network can handle over a given time. | +| **TTL** | Time To Live, a predefined time in which a message or node is deemed valid or active. | +| **UDP** | User Datagram Protocol. | +| **UUID** | Universally Unique Identifier, used to create a unique name for identification. | + +### 2.4. Network Definition + +This network protocol is built upon UDP (RFC 768) to ensure it can be implemented on any device capable of handling AP/STA concurrency. The protocol uses a specific, predefined set of connections to negate the issue of continuous network discovery. This means if a node knows its destination, it need not be aware of any other node in the network to route data. Only content locations need to be published, rather than complete routing tables. + +To maximize the number of devices, the network consists of a **distribution network** and a set of **client networks**. Each distribution node has its own client network and communicates with other nodes via NAT. In practical terms, if each distribution node serves 10 clients, a 4-node distribution network can facilitate communication for up to 44 devices. + +!!! warning "Throughput Limitation" + A significant drawback is that maximum throughput heavily depends on the number of hops a message must traverse. In a worst-case scenario, traffic passing from one end of the network to the other will pass through the root node, limiting throughput to the capacity of the root node's network interface. + +#### 2.4.1. Network Topology Description +The protocol uses a predefined tree graph structure to derive routing path information. This enables data routing without needing awareness of all other devices. + +The topology starts with a **root node** on the **root plane**, joined by a **replication node**. The next layer, plane **T1**, contains up to 4 distribution nodes. Plane **T2** can contain up to 8 nodes, and so on, up to plane **T9** with 1024 nodes. The theoretical maximum is 2046 distribution nodes, though this is likely unachievable due to throughput limitations. + +To leverage this topology, we use a private IP address range of `192.168.0.0/16`. +- The **third octet** identifies the network plane (`192.168.[plane].x`). +- The **fourth octet** identifies the node's position on that plane (`192.168.x.[position]`). + +![Centered image](../assets/diagrams/topology.png){ style="display: block; margin: 0 auto; width: 500px;" } + +The advantage of this topology is that it does not require a complex N² discovery method. If your node and the destination node exist, a routable path is guaranteed. + +#### 2.4.2. Network Initialization +The network is established by a single **root node**. The next device to connect becomes the **replicant node** on the root plane. The replicant node is identical for routing but forwards all data manifest updates to the root node to ensure a single source of truth. + +After the root plane is filled, child nodes can connect to parent nodes. Each child connects to two parent nodes (one primary, one secondary) to achieve redundancy. If one parent node fails, an alternate route still exists. + +#### 2.4.3. Handling Disconnects
+- **Graceful Disconnects:** A node intending to leave sends a disconnect message. This signals that its published data is no longer relevant and can be deleted from the data manifest.
+- **Ungraceful Disconnects:** If a node goes out of range or its application is terminated, it is considered active until a keep-alive TTL expires. After expiration, the node is deemed dead and a disconnect procedure is initiated.
+ +#### 2.4.4. Connection Boundaries +To prevent constant, costly network hopping, connection boundaries are defined using RSSI values. A node only seeks a new connection when its current one degrades past a certain threshold. The protocol describes 6 boundaries:
+- Minimum connection strength.
+- Minimum connection establishment strength.
+- Minimum/Maximum **primary** connection promotion strength.
+- Minimum/Maximum **secondary** connection promotion strength.
+ +!!! note "Implementation-Specific Values" + The specific RSSI values for these boundaries are left to the implementer, as they depend on the area of operation, device chipsets, and communication technology used. + +#### 2.4.5. Distribution Node Promotion Rules +When a distribution node reaches half its maximum client capacity, it triggers a promotion process. It requests a "fitness score" from all connected clients. The two nodes with the highest scores are chosen for promotion. The fitness score is calculated as follows: + +```mermaid +flowchart TD + %% Start Node + Start(Start: Calculate Fitness Score) + + %% Go/No-Go Checks + A{Has Tech
Capabilities?} + B{Has > 25%
Battery Life?} + C{Primary RSSI > Min
Promotion Strength?} + D{Secondary RSSI > Min
Promotion Strength?} + + %% Calculation Steps + E["1. Calculate Primary Score
Base = 100 + Primary RSSI
Apply penalty if RSSI > Max"] + F["2. Calculate Secondary Score
Add (100 + Secondary RSSI)
Apply penalty if RSSI > Max"] + + %% Final Adjustment + G{Has > 50%
Battery Life?} + H["3. Adjust for High Battery
Subtract 10 from score"] + + %% End Nodes + EndZero(Return Fitness Score: 0) + EndFinal(Return Final Fitness Score) + + %% Define Flow + Start --> A + A -- No --> EndZero + A -- Yes --> B + B -- No --> EndZero + B -- Yes --> C + C -- No --> EndZero + C -- Yes --> D + D -- No --> EndZero + D -- Yes --> E + + E --> F + F --> G + + G -- No --> H + H --> EndFinal + G -- Yes --> EndFinal +``` + +!!! tip "Note on RSSI" + RSSI values are negative, so a "higher" value is one that is closer to 0 (e.g., -55 dBm is a stronger signal than -75 dBm). + + +### 2.5. Nodes + +This chapter describes the behavior and functionality of the different node types. + +!!! note "Base Functionality" + Every node has the functionality of a **Client Node**. Distribution and Root nodes are specialized types that provide additional functionality. + +#### 2.5.1. Distribution Nodes +Distribution nodes form the network backbone, responsible for routing and caching data. When created, the first distribution node becomes the **root node**. Once five nodes are connected, the two "fittest" are promoted to become new distribution nodes, setting up their own Access Points for new clients. If a distribution node is full, it stops broadcasting its SSID until a slot becomes free. + +#### 2.5.2. Client Nodes +A client node is always connected to a distribution node's AP. It can publish and request data but cannot directly communicate with nodes it is not connected to. Upon connecting, it performs a handshake with the distribution node to confirm the connection and verify the integrity of the Data Manifest via a hash check. If a client loses connection, it will try to reconnect for 5 seconds before erasing its state and starting a new connection procedure. + +#### 2.5.3. Root Node +The root node is at the top of the network graph. It is responsible for providing the single source of truth for the **Data Manifest**. All updates to the manifest are sent to the root node. The root node initializes the network by creating the data structures and setting up the first Access Point with a specific SSID pattern: `[mesh identifier]-[mesh name]-[Tx]-[xxxx]`. This pattern is crucial for other nodes to discover the network. + +#### 2.5.4. Root Replication Node +This node is part of the root plane and shares routing responsibilities. However, it does not manage the Data Manifest itself unless the root node goes offline, at which point it becomes the acting root node until a new one is elected. + +#### 2.5.5. Node Connection Procedure +A node wishing to join first scans for Wi-Fi networks matching the predefined SSID pattern. If multiple distribution nodes are available, it selects the best one based on these rules:
+1. Filter for all nodes with an RSSI above the `minimum connection establishment strength`.
+2. From that list, select the nodes with the lowest network plane number (e.g., prefer T1 over T2).
+3. From the remaining list, pick the node with the highest RSSI value (strongest signal).
+ +This logic ensures the network grows compactly from the root outwards. + +```mermaid +sequenceDiagram + participant C as Client (Wi-Fi Library) + participant CL as Client (Connection Logic) + participant MH as Client (Message Handler) + participant DMH as Dist. Node (Message Handler) + participant DCL as Dist. Node (Connection Logic) + + C->>CL: Scan for all available networks + note over CL: 1. Compare list with SSID pattern + note over CL: 2. Filter by min. RSSI strength + note over CL: 3. Filter by lowest plane number + note over CL: 4. Select network with highest RSSI + CL-->>C: Return best SSID + + C->>CL: Configure STA interface with returned SSID + C->>CL: Connect to the network + + CL->>MH: send hello message + MH->>DMH: hello message + DMH->>DCL: source IP address + DCL-->>DCL: Add IP to TTL table + + DMH-->>MH: Return hello ack message + MH-->>CL: Receive hello ack message + CL-->>CL: Add IP to TTL table +``` +*Figure: The swimlane diagram illustrating the node connection process.* + +#### 2.5.6. Node Hopping and Connection Recovery +If a client node's connection degrades past a boundary, it sends a disconnect message and searches for a new parent. If a *distribution node's* connection degrades, it first tries to promote one of its own clients to take its place. If no clients are fit for promotion, it sends a disconnect message to its children and gracefully leaves the network. + +#### 2.5.7. TTL and Keep-Alives +Keep-alive timers ensure connectivity on unreliable connections. Each connection has a timer, and keep-alive messages are broadcast periodically to reset them. The TTL value is a critical tuning parameter: +- **Short TTL:** Better for highly dynamic networks with frequent disconnects, but increases traffic.
+- **Long TTL:** Better for more static networks, as it reduces data traffic.
+ +### 2.6. Defining the Routing Method + +#### 2.6.1. Network Routing + +The routing over this network happens according to the following rules. First, the node checks if the destination address is its own address. If so, the message is passed to the message handler. + +If the destination is not the local address, a check is performed to see if the address is a valid network address. If it is, the routing logic proceeds based on the interface the message arrived on: + +- **If a message arrives from the STA interface (from a parent/up the tree):** + - The message is forwarded to the destination if it is reachable on one of the node's child branches. + - The message is dropped if the destination is not reachable through this node's child branches. + +- **If a message arrives from the AP interface (from a child/down the tree):** + - The node checks if the destination is reachable on another child branch. If so, it forwards the message to that branch. + - Otherwise, the message is sent up the tree to the parent node. + +```mermaid +flowchart TD + A(Packet Arrives at Node) --> B{Is Destination == Local IP?} + B -- Yes --> C(Pass to Message Handler) + B -- No --> D{Which Interface Received Packet?} + + D -- STA (from Parent) --> E{Is Dest in any Child Branch?} + E -- Yes --> F(Forward to Child Branch) + E -- No --> G(Drop Packet) + + D -- AP (from Child) --> H{Is Dest in another Child Branch?} + H -- Yes --> I(Forward to other Child Branch) + H -- No --> J(Forward to Parent) +``` + + + +To know if a destination node is reachable on the current branch, the following calculation is performed. + +```pseudocode +// --- Define Input Variables --- +Pl = local_ip.third_octet +Ll = local_ip.fourth_octet +Pd = destination_ip.third_octet +Ld = destination_ip.fourth_octet + +// --- Calculate Distances --- +Plane_distance = Pd - Pl + +// --- Determine Reachable Bounds based on Node Position --- +if (Ll % 2 == 0) { + // Logic for EVEN numbered nodes + Reachable_upper_bound = Ll * (2^Pd) + Reachable_lower_bound = Reachable_upper_bound - (4 * Plane_distance) +} else { + // Logic for ODD numbered nodes + Reachable_upper_bound = (Ll + 1) * (2^Pd) + Reachable_lower_bound = Reachable_upper_bound - (4 * Plane_distance) +} + +// --- Final Check --- +if (Ld >= Reachable_lower_bound AND Ld <= Reachable_upper_bound) { + return REACHABLE +} else { + return NOT_REACHABLE +} +``` + +**If the local node's position (`Ll`) is an even number:** + +A destination is considered "on the current branch" if its position (`Ld`) is within the calculated `Reachable lower bound` and `Reachable upper bound`. + +!!! tip "Interface Selection" + Each node has two station interfaces. A message will always be sent through the interface whose address has a fourth octet that is mathematically closest to the fourth octet of the destination address. + +#### 2.6.2. Network Address Translation (NAT) +NAT is used between distribution and client nodes. Since the protocol listens on a specific port, a `NAT ID` field is added to the protocol header to identify the source client when forwarding messages into the distribution network and back. + +#### 2.6.3. Message Handler +The message handler sorts incoming packets by `message type` and calls the appropriate logic function, acting as the central traffic controller for the node. + +### 2.7. Data Definition + +#### 2.7.1. Packet Format +The protocol uses a custom header inside the data field of a standard UDP packet. + +```text +| 8bit | 8bit | 8bit | 8bit | +--------------------------------------------------------------------------------------- +| 32-bit Source Address | +--------------------------------------------------------------------------------------- +| 32-bit Destination Address | +--------------------------------------------------------------------------------------- +| Message Type (8) | TTL (8) | NAT ID (8) | Reserved (8) | +--------------------------------------------------------------------------------------- +| | +| | +| 20 bytes (160 bits) | +| SHA1 Hash | +| | +| | +--------------------------------------------------------------------------------------- +| | +. . +. MAX 65,448 bytes of Data . +. . +| | +--------------------------------------------------------------------------------------- +``` + + + + + +| Header Part | Size (bits) | Description | +| :--- | :--- | :--- | +| **Source Address** | 32 | `192.168.x.x` of the originating node. | +| **Destination Address**| 32 | `192.168.x.x` of the target node. | +| **Message Type** | 8 | Defines packet purpose (see table below). | +| **TTL** | 8 | Time To Live. | +| **NAT ID** | 8 | Identifier for NAT translation. | +| **Reserved** | 8 | For future use. | +| **SHA1 Hash** | 160 | Hash of the data payload for integrity checks. | +| **Data** | up to 65,448 bytes | The actual message payload. | + +!!! warning "Segmentation" + The current protocol does not handle packet segmentation. For messages larger than the maximum data size, a custom implementation would be required to split the data and re-assemble it, ensuring the custom header is stripped before processing. + +#### 2.7.2. Message Types +The `message type` field in the header dictates how the packet is handled. + +| Message Type | Value | Cacheable | +| :--- | :--- | :--- | +| default message | 0 | no | +| Hello message | 1 | no | +| Promotion message | 2 | no | +| Promotion ack message| 3 | no | +| Keep alive message | 4 | no | +| data manifest request| 5 | no | +| data manifest ack | 6 +| cacheable data message | 7 | yes | +| data manifest broadcast | 8 | no | +| data manifest delta broadcast | 9 | no | +| Promotion fitness request | 10 | no | +| Promotion fitness response | 11 | no | +| publication request | 12 | no | +| publication request response | 13 | no | +| Disconnect message | 14 | no | +| User defined | 20-30 | yes | +| User defined | 30-40 | no | + +!!! note "Reserved & User-Defined Types" + Values 7-19 are reserved for future system messages. Values 20-40 are available for custom, user-defined message types, provided a callback function is supplied to the message handler. + +2.7.3. Data Manifest Table +The Data Manifest is a table present on each node that holds the UUID and location (IP address) of published data. This could be anything from a website URL to the ID of a smartphone for direct messaging. + +!!! example "Example Data Manifest" +| Unique Identifier | IP Address | +| :--- | :--- | +| record 0 | 192.168.0.2 | +| record 1 | 192.168.3.4 | +| record 2 | 192.168.9.10 | + +To handle routing to specific client nodes, each distribution node also maintains a Local Manifest Table, which maps the data's UUID to the client's NAT ID. + +!!! example "Example Local Manifest Table" +| Unique Identifier | NAT ID | +| :--- | :--- | +| record 0 | 2 | +| record 1 | 4 | +| record 2 | 3 | + +The Data Manifest is versioned with a 32-bit integer. All modification requests are sent to the root node, which updates the master table and broadcasts the new version to the network. If a node disconnects, the distribution node it was connected to is responsible for removing its data records from the manifest. + +2.7.4. Data Caching +To minimize network traffic, distribution nodes can cache data from packets marked as cacheable. When a request for cached data is received, the node first sends the data's hash to the original source. The source verifies if the data is still valid. + +If valid, the source sends an ack message, and the distribution node serves the data from its cache. +If invalid (e.g., the data has been updated), the source sends the new data, which the distribution node then caches and forwards. +!!! example "Example Data Cache Table" +| Unique Identifier | Hash | Manifest Location | Data Location Pointer | +| :--- | :--- | :--- | :--- | +| record 0 | SHA1 Hash | Record 1 | 0xFFFF | +| record 1 | SHA1 Hash | Record 0 | 0XFFFF | +| record 2 | SHA1 Hash | Record 3 | 0xFFFF | + +### 2.8. Implementation Considerations + +#### 2.8.1. Security Considerations +!!! warning "Zero-Trust Network" + This network should be considered **insecure by default**. While individual links are secured with WPA3, the network password is known by all nodes. It is essential that any application built on this network uses a **zero-trust model** and implements its own **end-to-end encryption** for any data that needs to remain private. + +For secure networks, it is advised to have the host generate a random password and distribute it via a secure out-of-band method, such as scanning a QR code. + +#### 2.8.2. SSID Patterns and Provisioning +The SSID pattern `[mesh identifier]-[mesh name]-[Tx]-[xxxx]` is critical for network discovery. This pattern can either be hard-coded during implementation or supplied at runtime (e.g., via a QR code) to allow for multiple, distinct mesh networks. + +#### 2.8.3. Password Sharing and Provisioning Keys +The protocol is designed for Wi-Fi 6 and uses a single symmetric key (password) for the entire network. This key can be a predefined "provisioning key" for public networks or a unique password set by the host for private networks. To prevent unauthorized access, these keys should be stored securely on the device, for example, in a hardware-backed password vault. + +### 2.9. Bibliography +[1] J. Postel, „User Datagram Protocol,” RFC, 28 August 1980. +
[2] J. Moy, "OSPF Version 2," RFC 2328, April 1998. [Online]. Available: https://www.ietf.org/rfc/rfc2328.txt. + +Of course. I will format those sections into clean, readable Markdown tables as requested. + +Here is the formatted output: + +### 3. Submissions: The Research & Validation Roadmap +To validate and evolve this protocol, we will complete the following major submissions. + +| Objective ID | Submission Title | Core Goal | Status | +| :--- | :--- | :--- | :--- | +| `5_1_6_6...` | **Peer Review of Protocol v0.1** | To submit this document to external network scientists for peer review and feedback on its soundness. | :material-calendar: Planned | +| `5_2_6_6...` | **Simulation and Modeling** | To create a network simulation to test the protocol's behavior under various stress conditions (e.g., mass disconnects). | :material-calendar: Planned | +| `5_3_6_6...` | **Performance Benchmark Definition** | To define the Key Performance Indicators (KPIs) that the real-world implementation must meet to be considered a success. | :material-calendar: Planned | + +### 4. Role Management: Call for Contributions +This is a deep research project, and we need brilliant minds to ensure its scientific rigor. + +| Role ID | Role Title | Your Mission If You Join | +| :--- | :--- | :--- | +| `4_3_6` | **Mesh Network Researcher** | You will analyze, challenge, and improve the core routing and promotion algorithms defined in this protocol. | +| `4_8_6` | **Computer Scientist (Simulation)** | You will build the software models that simulate the Onlife network at scale to find its breaking points before we write a line of app code. | +| `4_9_6` | **Security Analyst** | You will analyze the protocol for theoretical vulnerabilities and help design a robust security model for applications built on top of it. | + +### 5. Team Budget + +| Item | Value (SC) | Status | +| :--- | :--- | :--- | +| **Total Phase 1 Budget:** | 0 | Awaiting initial crowdfunding | +| **SC Minted to Date:** | 0 | - | +| **Remaining Budget:** | 0 | Our first goal is to meet the Validation Phase crowdfunding target. | diff --git a/includes/glossary.md b/includes/glossary.md index 7be3b99..397f827 100644 --- a/includes/glossary.md +++ b/includes/glossary.md @@ -149,3 +149,25 @@ *[Technical Subsystem]: The suite of technological tools, processes, and economic models that enable collaborative production in a Smartup. Includes the dual-currency economy (Smartup Credits and Smartup Karma), the Four License System, the EU-sovereign open-source stack (Matrix/Element, Forgejo, Open Collective), the Smartup Administration Index for semantic numbering, and automation via Engelbot and CI/CD workflows. *[External Subsystem]: The framework that defines how Smartups operate as planetary organizations beyond national boundaries and political cycles. Emphasizes borderless digital participation, equal pay regardless of location, defocusing from partisan politics, resilience to regulatory volatility, and a roadmap to formal recognition as new organizational entities under global jurisdiction. + +*[Ack message]: A message that is used in order to acknowledge something. +*[AP or Access point]: A device that is used to connect clients to a network. +*[AP interface]: The network interface responsible for providing access point capabilities. +*[Child node]: The node that is directly connected to the parent node. A child node and parent node are always relative to each other. +*[Client network]: The network that is set up by each distribution node to serve data to clients. +*[Data Manifest]: The data manifest is a table used to store UUIDs and IP addresses of network accessible content. +*[Distribution network]: The network that links the distribution nodes together and provides connectivity to the entire mesh network. +*[Local data Manifest]: The local data manifest is a table used to provide NAT capabilities to the distribution node by coupling UUIDs to the NAT identifiers. +*[NAT]: Network address translation, a method used to serve multiple network devices using a single publicly facing IP address. +*[Network plane]: A single layer within the topology model. +*[Nodes]: Network capable devices that are part of the network. +*[Parent node]: A node that is acting as the connection point for the node directly connected to it below it, called the child node. +*[Root plane]: The topmost layer of the topology model. +*[RSSI]: A metric to describe the connection strength of a Wi--Fi network. +*[STA/AP concurrency]: AP/STA is a mode where a Wi-Fi capable device can simultaneously connect to an access point and be an access point at the same time. +*[STA interface]: The station interface is the network interface responsible for connecting to a Wi-Fi network. +*[SSID]: The broadcasted network name with which it can be identified. +*[Throughput]: The amount of data a network can handle over a given time. +*[TTL]: Time to live, a predefined amount of time in which a message or node is deemed valid or active. +*[UDP]: User Datagram Protocol. +*[UUID]: Universally unique identifier an identifier used to create a unique name for identification.