docs_tfgrid_get_started/docs/mycelium-network/architecture.md

---
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

<div className="info-box">

### 🔐 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.

</div>

## 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 (without identity-destination link, impossible to know if created by a MITM attacker)
- ❌ **Centralized certificate authorities** - Internet devices must be loaded with a list of trusted CAs
- ❌ **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.

<div className="info-box">

### 🌊 Real Example

This isn't just theoretical. We have experienced interruptions that were traceable with good certainty to **undersea cable cuts** happening at the same time. The network automatically routed around the failure using alternative paths.

</div>

**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 (e.g., `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 optimal path
5. **Decrypt at destination** - Using their 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

For more technical details:

- **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.
:::