ourworld_web/docs_projectmycelium
23
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
mik-tf
2025-11-25 15:27:56 -05:00
commit c769942374
33 changed files with 24049 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
docs/network/architecture.md Normal file
View File

@@ -0,0 +1,212 @@
---
sidebar_position: 4
---
# Mycelium Network Architecture
Understanding Mycelium's architecture reveals why it's fundamentally different from traditional networking solutions.
## Core Innovation: Identity = Address
Mycelium's architecture revolves around **peers**. Each peer has a cryptographic private/public keypair, and these are used to encrypt all messages in an end-to-end fashion.
The hash of the public key is used as an **IPv6 address**. This means that the cryptographic identity and the network address of each peer are **inherently linked**.
### What This Means in Practice
Think of it like a postal system where you can send a secret message to anyone just by knowing their address. The recipient can read it simply because they reside at the intended destination, without requiring any additional coordination or precommunication.
- **Your address IS your identity** – No separation between who you are and where you are
- **Automatic encryption** – Messages are encrypted to the destination by design
- **No key exchange needed** – The address itself contains the encryption key
:::info Technical Lineage
This innovation was pioneered by the **cjdns** network, which later inspired **Yggdrasil**, from which Mycelium is inspired. Each generation has refined and improved upon this fundamental concept.
:::
## Why This Is More Secure Than TLS/HTTPS
Compare this to the regular web, where most traffic is encrypted using TLS/HTTPS.
### The TLS Problem
In traditional TLS/HTTPS:
- ❌ **No inherent link** between a TLS cryptographic identity (certificate) and the destination of the traffic
- ❌ **Self-signed certificates** are rare and not considered secure
- ❌ **Centralized certificate authorities** – devices must trust an external CA list
- ❌ **Single points of failure** – CAs can be compromised, fail, or be coerced
### The Mycelium Solution
- ✅ **Cryptographic identity = Network address** – MITM attacks are cryptographically impossible
- ✅ **No trusted intermediaries** – No certificate authorities to compromise
- ✅ **Decentralized by design** – No single point of failure
- ✅ **Improved security and resiliency** – Both benefits simultaneously
## Network Architecture: Underlay & Overlay
Mycelium creates a **mesh network** to deliver encrypted IP overlay traffic. But how do peers actually connect?
### The Underlay Network
Mycelium peers must connect somehow to form the mesh. Most commonly, peers connect **over the regular internet**, using it as an **underlay network**.
This is enabled by **public peers** – special nodes that are open to receive connections on the regular internet.
```
┌──────────────────────────────────────────────────┐
│ Regular Internet (Underlay) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Public │ │ Public │ │ Public │ │
│ │ Peer A │ │ Peer B │ │ Peer C │ │
│ └────▲─────┘ └────▲─────┘ └────▲─────┘ │
│ │ │ │ │
└───────┼────────────────┼────────────────┼────────┘
│ │ │
┌───┴────┐ ┌───┴────┐ ┌───┴────┐
│ Your │◄─────►│ Your │◄─────►│ Your │
│Device 1│ Mesh │Device 2│ Mesh │Device 3│
└────────┘ └────────┘ └────────┘
Encrypted Mycelium Overlay Network
```
### The Overlay Network
On top of the underlay, Mycelium creates an **encrypted overlay** where:
- All traffic between your devices is end-to-end encrypted
- Routing is handled by the mesh protocol
- Your devices appear to be on the same local IPv6 network
## Resilient Multi-Path Routing
Here's where Mycelium achieves **more resilient routing than the regular internet**.
### How It Works
Each peer generally connects to **multiple public peers**, each offering a **different potential path** for traffic.
```
┌────────────────┐
│ Your Device │
└───┬─────┬─────┬┘
│ │ │
┌────────┤ │ └────────┐
│ │ │
┌───▼────┐ ┌───▼────┐ ┌────▼───┐
│Public │ │Public │ │Public │
│Peer 1 │ │Peer 2 │ │Peer 3 │
│Germany │ │Belgium │ │Finland │
└────────┘ └────────┘ └────────┘
Route A Route B Route C
```
### Real-World Resilience
If the route via one public peer is interrupted—such as by an **undersea cable cut**—there's a possibility to find another route via another public peer.
**Why the regular internet can't do this:**
- Most internet connections have a single ISP path
- BGP routing changes slowly and requires coordination
- No automatic multi-path at the user level
- Cable cuts can disconnect entire regions
**Why Mycelium can:**
- You're connected to multiple geographically diverse peers
- Mesh routing adapts automatically in seconds
- No coordination needed — it's peer-to-peer
- Traffic flows through available paths automatically
## Key Architectural Components
### 1. Cryptographic Keypair
Every Mycelium node generates:
- **Private key** – Kept secret, never shared
- **Public key** – Shared openly, identifies your node
### 2. IPv6 Address
Derived from your public key:
- **Format**: Standard IPv6 (for example `5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca`)
- **Unique**: Cryptographically guaranteed to be unique
- **Persistent**: Doesn't change unless you generate new keys
### 3. Peer Connections
Your node maintains connections to:
- **Public peers** – For internet connectivity and routing
- **Direct peers** – Other nodes you explicitly connect to
- **Discovered peers** – Nodes found through the mesh
### 4. Routing Table
Each node maintains:
- **Known peers** and their addresses
- **Path costs** to reach each peer
- **Multiple routes** to most destinations
- **Automatic updates** as the network changes
## Message Encryption Flow
When you send data to another Mycelium address:
1. **Lookup destination** – Find the IPv6 address.
2. **Derive public key** – Extract from the address.
3. **Encrypt message** – Using the destination's public key.
4. **Route through mesh** – Via the optimal path.
5. **Decrypt at destination** – Using the destination's private key.
Only the destination can decrypt — not even the public peers can read the content.
## Benefits of This Architecture
### Security Benefits
- **End-to-end encryption** – Built into the protocol
- **No MITM attacks** – Identity = Address prevents it
- **No trusted third parties** – Fully peer-to-peer
- **Private by default** – Encryption isn't optional
### Resilience Benefits
- **Multi-path routing** – Automatic failover
- **Self-healing** – Network adapts to failures
- **No single point of failure** – Fully distributed
- **Works behind NAT** – Firewall traversal built-in
### Simplicity Benefits
- **Zero configuration** – Just run and connect
- **Automatic key management** – No manual setup
- **Plug and play** – Works immediately
- **Cross-platform** – Same protocol everywhere
## Comparison with Other Technologies
| Feature | Mycelium | Traditional VPN | TLS/HTTPS | Tor |
|--------|----------|----------------|----------|-----|
| **Identity = Address** | ✅ Yes | ❌ No | ❌ No | ❌ No |
| **Decentralized** | ✅ Yes | ❌ Central server | ❌ Needs CAs | ✅ Yes |
| **Multi-path routing** | ✅ Yes | ❌ Single path | ❌ Single path | ✅ Yes |
| **Direct connections** | ✅ When possible | ❌ Via server | ✅ Yes | ❌ Via relays |
| **Zero config** | ✅ Yes | ❌ Needs setup | ✅ Browser only | ❌ Complex |
| **Performance** | ✅ Fast | ⚠️ Moderate | ✅ Fast | ❌ Slow |
## Technical Resources
- **Source Code** – [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
- **Yggdrasil Network** – [yggdrasil-network.github.io](https://yggdrasil-network.github.io)
- **cjdns Project** – [github.com/cjdelisle/cjdns](https://github.com/cjdelisle/cjdns)
:::tip Understanding Makes It Powerful
Now that you understand how Mycelium works, you can appreciate why it's not just another VPN – it's a fundamentally different approach to secure networking that eliminates entire classes of security problems.
:::