How It Works - Uqda Network

// OVERVIEW

This page explains how Uqda Network operates from the moment you install it until data is transmitted between nodes. We'll cover key generation, node identification, encryption, routing, and packet forwarding.

STEP 1: INSTALLATION

When you install Uqda, the system performs the following:

Package Installation: The installer places binaries in system directories
Service Setup: Creates system service for automatic startup (optional)
Binary Location: uqda (main daemon) and uqdactl (control utility)

# Linux installation example
sudo dpkg -i uqda-debian-amd64.deb

# Files installed:
# /usr/bin/uqda          - Main daemon
# /usr/bin/uqdactl       - Control utility
# /etc/uqda/             - Configuration directory (created on first run)

STEP 2: INITIALIZATION & KEY GENERATION

When Uqda starts for the first time:

2.1 Key Pair Generation

Uqda generates a cryptographic key pair using Ed25519:

Key Generation Process: 1. Generate Ed25519 Key Pair: ├─ Private Key (32 bytes) - KEPT SECRET └─ Public Key (32 bytes) - YOUR NODE IDENTITY 2. Private Key Storage: ├─ Option A: Random key (auto-config mode) └─ Option B: Loaded from file (config mode) 3. Public Key Usage: ├─ Node Identity (who you are) ├─ IPv6 Address Derivation └─ Encryption Target (others encrypt to you)

2.2 IPv6 Address Derivation

Your permanent IPv6 address is derived from your public key:

Algorithm:
1. Take public key (32 bytes)
2. Bitwise invert (NOT operation)
3. Count leading 1 bits
4. Truncate and format as IPv6
5. Result: Address in 0200::/7 range

Example:
Public Key: ed25519_public_key_bytes...
         ↓
IPv6 Address: 200:xxxx:xxxx:xxxx::1

2.3 Configuration File Creation

If using config file mode:

# Generate configuration
uqda -genconf > uqda.conf

# File contains:
{
  "PrivateKey": "base64_encoded_private_key",
  "Peers": [],
  "Listen": [],
  "AdminListen": "unix:///var/run/uqda.sock"
}

STEP 3: NODE STARTUP

When you run uqda:

3.1 Core Components Initialization

Startup Sequence: 1. Load Configuration ├─ Read private key ├─ Parse peer list └─ Set admin socket path 2. Initialize Core Components ├─ Core Router (routing engine) ├─ TUN Interface (virtual network) ├─ Link Manager (peer connections) ├─ Protocol Handler (routing protocol) └─ Admin Socket (control interface) 3. Create TUN Interface ├─ Linux: /dev/net/tun ├─ Windows: Wintun adapter └─ macOS: utun interface 4. Assign IPv6 Address └─ Your derived address: 200:xxxx:xxxx:xxxx::1

3.2 Network Interface Setup

The TUN interface appears in your system:

# Linux example
ip addr show uqda0
# Shows: inet6 200:xxxx:xxxx:xxxx::1/128

# Windows example
netsh interface ipv6 show address "Uqda"
# Shows your IPv6 address

STEP 4: ESTABLISHING PEER CONNECTIONS

Nodes connect to each other through peerings:

4.1 Static Peering (Manual)

# Add a peer
uqdactl addPeer tcp://peer.example.com:12345

# What happens:
1. DNS lookup (cached for 5 minutes)
2. TCP connection attempt (3s timeout)
3. Handshake exchange (5s timeout)
4. Key verification
5. Connection established

4.2 Handshake Process

Handshake Sequence: Node A Node B │ │ ├─ Connect TCP ────────────────>│ │ │ ├─ Send Metadata ──────────────>│ │ ├─ Public Key │ │ ├─ Protocol Version │ │ └─ Priority │ │ │ │<─ Receive Metadata ────────────┤ │ │ ├─ Verify Version ──────────────>│ │ │ │<─ Verify Version ─────────────┤ │ │ ├─ Connection Established <─────>│

4.3 Multicast Discovery (Automatic)

On local networks, nodes can discover each other automatically:

# Multicast beacon sent to: [ff02::114]:9001
# Any node on same subnet receives beacon
# Automatic peering attempt initiated
# No configuration needed!

STEP 5: ROUTING PROTOCOL

Once connected, nodes exchange routing information:

5.1 Spanning Tree Construction

Tree Building: 1. Root Selection └─ Node with lowest public key becomes root 2. Tree Propagation ├─ Root broadcasts tree info ├─ Each node calculates distance └─ Coordinates assigned 3. Tree Structure: Root (lowest key) / \ Node A Node B / \ | Node C Node D

5.2 Keyspace Routing (DHT)

Nodes exchange bloom filters describing reachable keys:

# Each node maintains:
- Bloom filter of reachable keys
- Routing table entries
- Path information

# When forwarding:
1. Check if destination in local bloom filter
2. If yes, forward to known path
3. If no, forward toward keyspace position
4. Intermediate nodes update routing tables

STEP 6: ENCRYPTION & DECRYPTION

All traffic is encrypted end-to-end:

6.1 Encryption Process (Sending)

Encryption Pipeline: Application Data (Plaintext) │ ▼ ┌───────────────────┐ │ Get Destination │ │ Public Key │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ Generate Ephemeral│ │ Key (X25519) │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ ChaCha20-Poly1305 │ │ Encryption │ │ ├─ Stream cipher │ │ └─ Auth tag │ └─────────┬─────────┘ │ ▼ Encrypted Packet (Ciphertext)

6.2 Decryption Process (Receiving)

Decryption Pipeline: Encrypted Packet Received │ ▼ ┌───────────────────┐ │ Extract Metadata │ │ (ephemeral key) │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ Derive Session │ │ Key (X25519) │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ ChaCha20-Poly1305 │ │ Decryption │ │ ├─ Verify tag │ │ └─ Decrypt data │ └─────────┬─────────┘ │ ▼ Application Data (Plaintext)

6.3 Key Exchange Details

# For each packet:
1. Sender generates ephemeral key pair (X25519)
2. Uses destination's public key (Ed25519 → X25519)
3. Derives shared secret
4. Encrypts with ChaCha20-Poly1305
5. Receiver uses own private key to decrypt

# Forward Secrecy:
- Each packet uses new ephemeral key
- Compromised key doesn't affect past traffic
- Future traffic remains secure

STEP 7: PACKET FORWARDING

How packets travel through the network:

7.1 Sending a Packet

Packet Journey: Your Application │ ├─ Sends IPv6 packet to: 200:yyyy:yyyy:yyyy::1 │ ▼ TUN Interface (uqda0) │ ├─ Uqda receives packet │ ▼ Routing Engine │ ├─ Looks up destination in routing table ├─ Finds path: You → Node A → Node B → Destination │ ▼ Encryption Layer │ ├─ Encrypts with destination's public key │ ▼ Link Manager │ ├─ Forwards to Node A (first hop) │ ▼ Node A (Intermediate) │ ├─ Receives encrypted packet ├─ Cannot decrypt (doesn't have destination key) ├─ Looks up next hop: Node B ├─ Forwards to Node B │ ▼ Node B (Intermediate) │ ├─ Receives encrypted packet ├─ Cannot decrypt ├─ Forwards to Destination │ ▼ Destination Node │ ├─ Receives encrypted packet ├─ Decrypts with own private key ├─ Delivers to application │ ▼ Destination Application

7.2 Routing Decision

# Routing algorithm:
1. Check if destination is direct peer
   └─ If yes: send directly

2. Check routing table for path
   └─ If found: forward to next hop

3. Use keyspace routing (DHT)
   └─ Forward toward destination's key position

4. Fallback to spanning tree
   └─ Use tree routing if DHT fails

STEP 8: REAL-WORLD EXAMPLES

8.1 Sending a File

# Scenario: Send file via SCP

You run: scp file.txt user@[200:yyyy:yyyy:yyyy::1]:/home/user/
SCP creates TCP connection to destination
TCP packets sent to uqda0 interface
Uqda encrypts each packet with destination's public key
Packets routed through network (encrypted at each hop)
Destination receives encrypted packets
Destination decrypts with own private key
TCP connection established, file transfer begins

8.2 Playing a Game

# Scenario: Multiplayer game connection

Game client connects to server at [200:zzzz:zzzz:zzzz::1]
Each game packet (position, actions) sent via Uqda
Packets encrypted end-to-end
Low latency routing (direct path when possible)
Server receives encrypted packets, decrypts
Game state synchronized securely

8.3 Traceroute (Path Discovery)

# Run traceroute to see path
traceroute -6 200:yyyy:yyyy:yyyy::1

# Output shows:
1  200:xxxx:xxxx:xxxx::1 (your node)    0.000 ms
2  200:aaaa:aaaa:aaaa::1 (Node A)       15.234 ms
3  200:bbbb:bbbb:bbbb::1 (Node B)       28.567 ms
4  200:yyyy:yyyy:yyyy::1 (destination)  35.123 ms

# Each hop represents:
- A node forwarding your packet
- Encryption/decryption at each hop (for routing)
- But payload remains encrypted to destination

STEP 9: NETWORK MAINTENANCE

9.1 Automatic Path Recovery

If a link fails:

# What happens:
Node detects connection loss
Routing table updated
Alternative path discovered
Traffic rerouted automatically
No manual intervention needed

9.2 Connection Monitoring

# Check your connections
uqdactl getPeers

# Output:
Peer: tcp://peer.example.com:12345
  ├─ Status: Connected
  ├─ Uptime: 2h 15m
  ├─ Bytes RX: 1.2 GB
  ├─ Bytes TX: 850 MB
  └─ Latency: 25ms

// SUMMARY

The Complete Flow:

Installation: System setup and binary installation
Key Generation: Ed25519 key pair created, IPv6 address derived
Node Startup: TUN interface created, core components initialized
Peering: Connections established with other nodes (manual or automatic)
Routing: Network topology discovered, routing tables built
Encryption: All traffic encrypted with destination's public key
Forwarding: Packets routed through network, encrypted at each hop
Decryption: Destination decrypts with own private key
Delivery: Data delivered to application

Key Security Features:

End-to-end encryption (intermediate nodes cannot read payload)
Forward secrecy (ephemeral keys for each packet)
Cryptographic identity (public key = node identity)
Permanent addressing (IPv6 address tied to identity)

UQDA NETWORK