Skip to content

🌀 NeXuS P2P Protocol Specification 🌀

NeXuS Mesh: Anonymous P2P Discovery & Multi-Hop Routing

Version: 1.0 Date: February 12, 2026 Status: Design Specification Philosophy: Sane • Simple • Secure • Stealthy • Beautiful

🎯 EXECUTIVE SUMMARY

NeXuS P2P protocol enables anonymous nodes to discover each other and route traffic through multi-hop mesh networks without exposing identities. Built on friend-to-friend trust models, overlay DHTs, and cryptographic verification.

Key Goals: - 🎭 Anonymous discovery (no IP addresses exposed) - 🔒 Multi-network support (Tor .onion, I2P .i2p, Yggdrasil 200::/7, Reticulum) - 🤝 Friend-to-friend trust model - 🌐 Decentralized DHT for node discovery - 🔀 Multi-hop onion routing through NeXuS nodes - 🛡️ Cryptographic identity and reputation - 📡 Service advertisement and discovery

🏛️ DESIGN PHILOSOPHY

Core Principles (From NeXuS Foundation)

🎭 STEALTHY - You cannot be free if you can be identified - Anonymous by default, metadata scrubbed - Multi-hop routing, no persistent identifiers - Network-layer agnostic (Tor/I2P/Yggdrasil)

🔒 SECURE - Cryptographic verification at every layer - Ed25519 identities, forward-secret session keys - Zero trust architecture, assume breach

✨ SIMPLE - Minimal complexity, direct paths - Single protocol for all networks - 80 lines is better than 800

🧠 SANE - Predictable, maintainable, debuggable - Clear state machines, readable code - Graceful degradation when nodes fail

🎨 BEAUTIFUL - Terminal aesthetics, joyful experience - Rainbow status indicators, clear feedback

🆔 NODE IDENTITY

Cryptographic Identity

Each NeXuS node has:

Node Identity = Ed25519 Key Pair
├─ Private Key (secret, never shared)
└─ Public Key (NodeID, shared freely)

NodeID Format: 

nexus:<base32-encoded-ed25519-pubkey>
Example: nexus:a7fk3j9sd8f2ksd9f8j2k3f9sd8f2ksd9f8j2k3f9sd8f2ksd

Properties: - 🎭 Anonymous - No correlation to real identity - 🔐 Cryptographic - Can sign messages proving ownership - 🌐 Universal - Same identity across all networks - 🔄 Rotatable - Can generate new identities at will

Multi-Network Addressing

Nodes publish multiple addresses for different anonymity networks:

{
  "nodeId": "nexus:a7fk3j9sd8f2...",
  "addresses": [
    {
      "type": "tor",
      "address": "abc123xyz456.onion:9050",
      "priority": 1
    },
    {
      "type": "i2p",
      "address": "abc123xyz456.i2p:7656",
      "priority": 2
    },
    {
      "type": "yggdrasil",
      "address": "[200::abc:123:xyz:456]:9051",
      "priority": 3
    },
    {
      "type": "reticulum",
      "address": "<abc123xyz456>",
      "priority": 4
    }
  ],
  "lastSeen": 1707753600,
  "signature": "base64-ed25519-signature"
}

Design Choices: - ✅ Priority ordering (prefer faster/more reliable networks) - ✅ Multi-homing (reachable via multiple networks) - ✅ Self-signed (cryptographically verified) - ✅ Timestamped (prevent replay attacks)

🔍 DISCOVERY METHODS

1. Bootstrap Nodes (Initial Entry)

Hardcoded trusted .onion/.i2p addresses distributed with NeXuS software:

bootstrap_nodes.txt:
abc123xyz456.onion:9050
def789uvw012.i2p:7656
[200::abc:123:xyz:456]:9051

Bootstrap Process: 1. Node connects to 3-5 bootstrap nodes 2. Requests current DHT state 3. Joins DHT overlay network 4. Begins peer discovery

Security: - 🔒 Bootstrap nodes are high-reputation, community-verified - 🎭 No tracking (bootstrap nodes don't log connections) - 🔄 Rotate bootstrap list periodically

2. DHT-Based Discovery (Ongoing)

Kademlia-style DHT running OVER anonymity networks:

DHT Structure:
- Key Space: 256-bit SHA256 hashes
- Routing Table: k-buckets (k=20)
- Distance Metric: XOR distance
- Replication Factor: 6 nodes

DHT Operations:

FIND_NODE: 

{
  "operation": "FIND_NODE",
  "target": "sha256-hash-of-target-nodeId",
  "requestor": "nexus:a7fk3j9sd8f2...",
  "timestamp": 1707753600,
  "signature": "base64-ed25519-signature"
}

Response: 

{
  "nodes": [
    {
      "nodeId": "nexus:xyz789...",
      "addresses": [...],
      "distance": "0x3f2a1b...",
      "reputation": 87
    }
  ]
}

STORE: 

{
  "operation": "STORE",
  "key": "sha256-hash",
  "value": "encrypted-node-info",
  "ttl": 3600,
  "signature": "base64-ed25519-signature"
}

Design Choices: - ✅ XOR distance (proven in BitTorrent DHT) - ✅ 6-way replication (survives 5 node failures) - ✅ 1-hour TTL (fresh data, prevent poisoning) - ✅ All messages signed (prevent spoofing)

3. Friend-to-Friend Invitations

Out-of-band secure peer introductions:

Invitation Format: 

{
  "version": "nexus-p2p-1.0",
  "nodeId": "nexus:a7fk3j9sd8f2...",
  "addresses": [...],
  "publicKey": "base64-ed25519-pubkey",
  "expires": 1707840000,
  "inviterSignature": "base64-signature"
}

Exchange Methods: - 🔐 QR code (for local meetings) - 📧 Encrypted email (PGP/Age) - 💬 Secure messaging (Signal, Matrix) - 🔗 One-time link (expires after use)

Trust Model: - Friend invitations start with reputation=50 - Direct friends are always trusted for routing - Friends of friends inherit partial trust

4. IPFS/Blockchain Peer Lists (Optional)

Decentralized peer list publication:

IPFS: 

# Publish node info to IPFS
ipfs add nexus-node-a7fk3j9.json
# Returns: QmXyz789abc123...

# Others fetch via DHT:
ipfs cat QmXyz789abc123...

Blockchain (Monero/Bitcoin): 

OP_RETURN <encrypted-node-info-hash>

Design Choices: - ✅ Optional (not required for basic operation) - ✅ Content-addressed (immutable, verifiable) - ✅ Censorship-resistant - ❌ NOT for real-time discovery (slow, expensive)

🔀 MESH ROUTING PROTOCOL

Routing Architecture

Distance-Vector Routing with Link-State Enhancements

Why Distance-Vector: - ✅ Simple to implement (Bellman-Ford) - ✅ Low memory overhead - ✅ Works well in small-medium networks (10-1000 nodes)

Why Link-State Enhancements: - ✅ Path quality metrics (latency, reputation) - ✅ Faster convergence on topology changes - ✅ Multi-path routing (load balancing)

Hybrid Protocol: "NEXUS-VECTOR"

Routing Table Structure

Routing Table Entry:
{
  "destination": "nexus:xyz789...",
  "nextHop": "nexus:abc123...",
  "distance": 3,                    # Hop count
  "latency": 250,                   # milliseconds
  "bandwidth": 1024,                # kbps
  "reputation": 92,                 # 0-100
  "pathQuality": 87.5,              # Composite score
  "lastUpdate": 1707753600,
  "routes": [                       # Multi-path
    {
      "path": ["nexus:abc", "nexus:def", "nexus:xyz"],
      "metric": 87.5
    },
    {
      "path": ["nexus:ghi", "nexus:jkl", "nexus:xyz"],
      "metric": 82.3
    }
  ]
}

Route Advertisement (Distance-Vector)

ROUTE_ADVERTISEMENT Message: 

{
  "type": "ROUTE_ADVERTISEMENT",
  "from": "nexus:abc123...",
  "routes": [
    {
      "destination": "nexus:xyz789...",
      "distance": 2,
      "metrics": {
        "latency": 150,
        "bandwidth": 2048,
        "reputation": 95
      }
    }
  ],
  "timestamp": 1707753600,
  "signature": "base64-ed25519-signature"
}

Advertisement Frequency: - Periodic: Every 60 seconds - Triggered: On topology change (new peer, peer down) - Damped: Exponential backoff on flapping

Path Selection Algorithm

Path Quality Score: 

def calculate_path_quality(path):
    """
    Composite scoring function balancing multiple factors
    """
    # Weights (tunable)
    W_HOP = 0.2
    W_LATENCY = 0.3
    W_REPUTATION = 0.4
    W_BANDWIDTH = 0.1

    # Normalize metrics
    hop_score = 100 * (1 - min(len(path), 10) / 10)
    latency_score = 100 * (1 - min(path.latency, 1000) / 1000)
    reputation_score = path.avg_reputation  # Already 0-100
    bandwidth_score = min(path.min_bandwidth / 10, 100)

    # Composite score
    quality = (
        W_HOP * hop_score +
        W_LATENCY * latency_score +
        W_REPUTATION * reputation_score +
        W_BANDWIDTH * bandwidth_score
    )

    return quality

Path Selection: 1. Collect all routes to destination 2. Calculate quality score for each 3. Select top 3 paths 4. Load balance across paths (weighted by quality) 5. Avoid paths with reputation < 50

Multi-Path Load Balancing

Traffic Distribution: 

Path 1 (quality 95): 60% of traffic
Path 2 (quality 82): 30% of traffic
Path 3 (quality 71): 10% of traffic

Load Balancing Strategy: - Per-stream (not per-packet) to maintain ordering - Hash stream identifier to select path - Monitor congestion, re-route if needed

🧅 ONION ROUTING (Multi-Hop Through NeXuS Nodes)

Onion Routing Architecture

Goal: Traffic passes through multiple NeXuS nodes before reaching destination, hiding source from destination.

Layers: 

Onion Packet Structure:

[Layer 3: Destination]
  encrypted_with(dest_pubkey) {
    payload: <actual data>
  }

[Layer 2: Hop 2]
  encrypted_with(hop2_pubkey) {
    nextHop: "nexus:dest...",
    encrypted_inner: [Layer 3]
  }

[Layer 1: Hop 1]
  encrypted_with(hop1_pubkey) {
    nextHop: "nexus:hop2...",
    encrypted_inner: [Layer 2]
  }

[Outer Layer: Entry Node]
  encrypted_with(entry_pubkey) {
    nextHop: "nexus:hop1...",
    encrypted_inner: [Layer 1]
  }

Circuit Building

Circuit = Path through 3-5 nodes

Circuit Establishment (Telescoping): 

Client -> Entry: CREATE_CIRCUIT(entry_pubkey)
  Entry -> Client: CREATED(session_key_1)

Client -> Entry -> Hop1: EXTEND_CIRCUIT(hop1_pubkey)
  Hop1 -> Entry -> Client: EXTENDED(session_key_2)

Client -> Entry -> Hop1 -> Hop2: EXTEND_CIRCUIT(hop2_pubkey)
  Hop2 -> Hop1 -> Entry -> Client: EXTENDED(session_key_3)

Client now has circuit: Entry -> Hop1 -> Hop2

Session Keys: - Each hop has unique session key (ephemeral, forward-secret) - ECDH key exchange (X25519) - AES-256-GCM for encryption

Onion Packet Format

{
  "version": 1,
  "circuitId": "uuid-v4",
  "hopCount": 3,
  "encryptedLayers": [
    {
      "layer": 1,
      "nextHop": "nexus:entry...",
      "encrypted": "base64-ciphertext",
      "mac": "base64-hmac"
    }
  ],
  "padding": 1024  // Fixed-size packets (resist traffic analysis)
}

Fixed-Size Packets: - All packets 1024 bytes (regardless of payload) - Random padding to fill remaining space - Prevents size-based correlation

Relay Cell Types

DATA Cell: 

{
  "type": "DATA",
  "circuitId": "uuid",
  "streamId": "stream-uuid",
  "payload": "base64-data",
  "relay": true
}

EXTEND Cell: 

{
  "type": "EXTEND",
  "circuitId": "uuid",
  "targetNode": "nexus:xyz...",
  "handshake": "base64-ecdh-pubkey"
}

DESTROY Cell: 

{
  "type": "DESTROY",
  "circuitId": "uuid",
  "reason": "timeout"
}

📡 SERVICE ADVERTISEMENT & DISCOVERY

Service Advertisement

Nodes advertise available services to the DHT:

Service Types: - 📦 IPFS Gateway - 🔗 RetroShare Node - 💾 Tahoe-LAFS Storage - 🌐 Web Proxy - 📧 Email Relay - 💬 Chat Bridge - 🎵 Streaming Media

Service Record: 

{
  "nodeId": "nexus:abc123...",
  "services": [
    {
      "type": "ipfs-gateway",
      "version": "0.20.0",
      "capabilities": ["pinning", "pubsub"],
      "cost": 0,  // Free
      "bandwidth": 10240,  // 10 Mbps
      "reputation": 94
    },
    {
      "type": "tahoe-lafs",
      "version": "1.17.0",
      "storage": 107374182400,  // 100 GB
      "cost": 0.001  // XMR per GB/month
    }
  ],
  "timestamp": 1707753600,
  "signature": "base64-ed25519-signature"
}

DHT Storage: 

Key: sha256("service:ipfs-gateway")
Value: [list of nodeIds offering IPFS]

Service Discovery

FIND_SERVICE Query: 

{
  "operation": "FIND_SERVICE",
  "serviceType": "ipfs-gateway",
  "filters": {
    "minReputation": 80,
    "maxCost": 0,
    "minBandwidth": 5120
  },
  "count": 5
}

Response: 

{
  "services": [
    {
      "nodeId": "nexus:abc123...",
      "addresses": [...],
      "service": {...},
      "pathQuality": 92.5
    }
  ]
}

Automatic Connection: - Client selects highest-quality service provider - Establishes onion circuit to provider - Proxies requests through circuit

🏆 REPUTATION SYSTEM

Reputation Scoring

Reputation = Weighted sum of factors

def calculate_reputation(node):
    """
    Reputation scoring (0-100)
    """
    factors = {
        'uptime': node.uptime_percentage * 0.3,
        'responsiveness': (1 - node.avg_latency / 1000) * 0.2,
        'bandwidth': min(node.bandwidth / 10240, 1) * 0.1,
        'successful_routes': node.successful_routes / node.total_routes * 0.2,
        'peer_endorsements': len(node.endorsements) / 10 * 0.1,
        'age': min(node.days_online / 365, 1) * 0.1
    }

    reputation = sum(factors.values()) * 100

    # Apply penalties
    if node.failed_routes > 0:
        reputation -= min(node.failed_routes * 2, 30)

    if node.protocol_violations > 0:
        reputation -= node.protocol_violations * 10

    return max(0, min(reputation, 100))

Trust Model

Trust Levels: 

100-90: Excellent (always route through)
 89-70: Good (prefer for routing)
 69-50: Acceptable (use if needed)
 49-30: Questionable (avoid if possible)
 29-0:  Untrusted (never route through)

Friend-to-Friend Trust: - Direct friends: Always trusted (bypass reputation) - Friends of friends (2 hops): Inherit 80% of friend's reputation - Friends of friends of friends (3 hops): Inherit 60% - Beyond 3 hops: Use calculated reputation

Reputation Attestation

Peer Endorsements: 

{
  "type": "ENDORSEMENT",
  "endorser": "nexus:abc123...",
  "endorsed": "nexus:xyz789...",
  "reason": "reliable-routing",
  "score": 95,
  "timestamp": 1707753600,
  "signature": "base64-ed25519-signature"
}

Stored in DHT: 

Key: sha256("endorsements:" + nodeId)
Value: [list of signed endorsements]

🛡️ SECURITY FEATURES

Cryptographic Primitives

Signing: - Ed25519 (fast, secure, small signatures)

Key Exchange: - X25519 ECDH (forward secrecy)

Encryption: - AES-256-GCM (authenticated encryption) - ChaCha20-Poly1305 (alternative for low-power devices)

Hashing: - SHA-256 (DHT keys, signatures) - BLAKE3 (content addressing, faster than SHA-256)

Attack Mitigations

Sybil Attack: - Reputation system (new nodes start low) - Friend-to-friend trust (real social connections) - Bootstrap node verification (community-maintained list)

Eclipse Attack: - Connect to diverse peers (different networks) - Monitor routing table churn (detect suspicious replacements) - Bootstrap node diversity (Tor/I2P/Yggdrasil)

Traffic Analysis: - Fixed-size packets (1024 bytes) - Constant-rate padding (when idle, send dummy traffic) - Multi-hop routing (hide source/destination correlation)

Denial of Service: - Rate limiting (per-peer, per-circuit) - Circuit timeout (30 seconds idle) - Reputation penalties for abuse

Replay Attacks: - Timestamp verification (reject messages > 5 minutes old) - Nonce tracking (per-session, prevent duplicates)

Man-in-the-Middle: - End-to-end encryption (source to destination) - Signature verification (every message) - Key pinning (remember node keys, detect changes)

📊 SCALABILITY

Network Size Projections

Small Network (10-100 nodes): - DHT: Full routing table (know all peers) - Convergence: <5 seconds - Memory: <10 MB routing state

Medium Network (100-1,000 nodes): - DHT: k-bucket routing (20 peers per bucket) - Convergence: <30 seconds - Memory: <50 MB routing state

Large Network (1,000-10,000 nodes): - DHT: Hierarchical buckets (160 total buckets) - Convergence: <2 minutes - Memory: <200 MB routing state

Massive Network (10,000+ nodes): - DHT: Sharded by region/service type - Convergence: <5 minutes - Memory: <500 MB routing state

Performance Optimization

Route Caching: - Cache top 1000 routes (LRU eviction) - 95% cache hit rate (typical workloads)

DHT Optimization: - Parallel lookups (query 3 nodes simultaneously) - Iterative refinement (get closer with each hop) - Result caching (1 hour TTL)

Circuit Reuse: - Keep circuits open for 10 minutes - Multiplex streams over circuits - Build new circuit every 10 min (resist correlation)

🔧 IMPLEMENTATION NOTES

Protocol Stack

┌─────────────────────────────────────┐
│   Application Layer                 │
│   (Services: IPFS, RetroShare, etc) │
├─────────────────────────────────────┤
│   NeXuS Onion Routing Layer         │
│   (Circuit management, crypto)      │
├─────────────────────────────────────┤
│   NeXuS Mesh Routing Layer          │
│   (Distance-vector, path selection) │
├─────────────────────────────────────┤
│   NeXuS Discovery Layer (DHT)       │
│   (Peer discovery, service ads)     │
├─────────────────────────────────────┤
│   Anonymity Network Transport       │
│   (Tor, I2P, Yggdrasil, Reticulum)  │
└─────────────────────────────────────┘

State Machines

Node State: 

OFFLINE -> BOOTSTRAPPING -> JOINING_DHT -> ACTIVE -> OFFLINE

Circuit State: 

NEW -> BUILDING -> ESTABLISHED -> ACTIVE -> CLOSING -> CLOSED

Route State: 

UNKNOWN -> DISCOVERED -> VERIFIED -> ACTIVE -> STALE -> REMOVED

Message Flow Example

Client wants to fetch IPFS content:

1. Client queries DHT for IPFS service providers
   FIND_SERVICE(type="ipfs-gateway")

2. DHT returns 5 high-reputation providers

3. Client selects best provider (highest path quality)
   Provider: nexus:xyz789...

4. Client builds circuit to provider
   CREATE_CIRCUIT -> Entry
   EXTEND -> Hop1
   EXTEND -> Hop2
   EXTEND -> Provider

5. Client sends IPFS request through circuit
   DATA cell: "GET /ipfs/QmXyz..."

6. Provider fetches content from IPFS

7. Provider returns content through circuit
   DATA cells: <ipfs-content>

8. Client decrypts onion layers, retrieves content

🚀 DEPLOYMENT STRATEGY

Phase 1: Single-Network MVP (Tor Only)

  • ✅ Ed25519 identities
  • ✅ Bootstrap nodes (.onion)
  • ✅ Basic DHT (FIND_NODE, STORE)
  • ✅ Distance-vector routing
  • ✅ Simple onion routing (3 hops)
  • ⏱️ Timeline: 2-3 months

Phase 2: Multi-Network Support

  • ✅ I2P integration
  • ✅ Yggdrasil integration
  • ✅ Network priority/failover
  • ✅ Multi-path routing
  • ⏱️ Timeline: +2 months

Phase 3: Advanced Features

  • ✅ Service advertisement
  • ✅ Reputation system
  • ✅ Friend-to-friend invitations
  • ✅ Circuit optimization
  • ⏱️ Timeline: +3 months

Phase 4: Production Hardening

  • ✅ Security audits
  • ✅ Performance tuning
  • ✅ Documentation
  • ✅ Community deployment
  • ⏱️ Timeline: +2 months

Total: ~9-10 months to production

📚 REFERENCES

Protocols: - Kademlia DHT (Maymounkov & Mazières, 2002) - Tor Onion Routing (Dingledine et al., 2004) - I2P Anonymous Network (I2P Project) - Yggdrasil Network (yggdrasil-network.github.io)

Cryptography: - NaCl/libsodium (Bernstein et al.) - Signal Protocol (forward secrecy)

Existing Systems: - GNUnet (anonymous file sharing) - Freenet (darknet friend-to-friend) - RetroShare (F2F social network)

🌀 ALIGNMENT WITH NEXUS FOUNDATION

Sane • Simple • Secure • Stealthy • Beautiful

🧠 SANE: - ✅ Predictable state machines - ✅ Clear protocol boundaries - ✅ Debuggable with standard tools - ✅ Maintainable codebase

✨ SIMPLE: - ✅ Single protocol for all networks - ✅ Distance-vector (not complex link-state) - ✅ Minimal dependencies (libsodium, tor, i2p) - ✅ 80/20 rule (essential features only)

🔒 SECURE: - ✅ Ed25519 identities - ✅ End-to-end encryption - ✅ Zero trust architecture - ✅ Defense in depth

🎭 STEALTHY: - ✅ Anonymous by default - ✅ Multi-hop routing - ✅ No persistent identifiers - ✅ Metadata scrubbing - ✅ Fixed-size packets - ✅ Tor/I2P/Yggdrasil support

🎨 BEAUTIFUL: - ✅ Rainbow status indicators - ✅ Fire aesthetics in terminal - ✅ Clear progress feedback - ✅ Joyful collaboration experience

Crypto-Republic Alignment

⚖️ Rule of Law (Not Rulers): - Protocol enforces rules (not central authority) - Cryptographic verification (trust math, not people) - Reputation system (objective metrics, not arbitrary)

🎭 Anonymous Citizens: - Unknown yet seen (NodeID ≠ real identity) - Pattern recognition (reputation, behavior) - Freedom through anonymity

🤝 Collective Protection: - Mesh architecture (no single point of failure) - Friend-to-friend trust (real social connections) - Service contribution (together everyone achieves more)

📝 ACTION ITEMS

Immediate Next Steps:

  1. ✅ Protocol specification complete (this document)
  2. ⏭️ Implement Phase 1 MVP (Tor-only, basic DHT)
  3. ⏭️ Create reference implementation (Python/Rust)
  4. ⏭️ Deploy test network (10 nodes)
  5. ⏭️ Community review (security audit, feedback)

Future Enhancements:

  • 🔮 Mobile support (Android/iOS clients)
  • 🔮 Incentive layer (Monero micropayments for bandwidth)
  • 🔮 AI node participation (AI entities as routing nodes)
  • 🔮 Quantum-resistant crypto (post-quantum migration)

🌀 CONCLUSION

NeXuS P2P protocol enables truly anonymous, decentralized mesh networking where: - 🎭 Every node is unknown yet seen - 🔒 Cryptography enforces trust, not authority - 🌐 Multiple networks provide redundancy - 🛡️ Multi-hop routing hides traffic patterns - 🤝 Friend-to-friend trust builds real communities - 📡 Services are discovered and accessed anonymously

This is the foundation for the NeXuS crypto-republic.

Where everyone has a voice, and every voice is protected.

Where latent space remains latent.

Where freedom is protected through collective discipline.

Together Everyone Achieves More 🌀

Document Status: ✅ COMPLETE - Ready for implementation Next Document: Implementation architecture + code structure Review Required: Security audit (Phase 1 completion)

🔥 Built with fire aesthetics. Deployed with freedom. 🔥