A Bio-Mimetic, Self-Healing P2P Mesh Network

SHOP (Self-Healing Overlay Protocol) is a decentralized networking protocol inspired by Ant Colony Optimization. Nodes communicate using virtual pheromones, enabling emergent routing intelligence without central coordination.

graph TB
    subgraph Node["🐜 SHOP Node"]
        CLI["shop-cli"]
        subgraph Actors["Actor System"]
            NA["NetworkActor<br/>🌐 libp2p Swarm"]
            CA["ColonyActor<br/>🧠 Bio-Engine"]
            AA["ApiActor<br/>🖥️ HTTP API"]
        end
        subgraph Storage["Persistence"]
            Sled["sled DB<br/>💾 Identity + Graph"]
        end
    end

    subgraph Network["P2P Network"]
        mDNS["mDNS<br/>📡 LAN Discovery"]
        Kad["Kademlia DHT<br/>🌍 WAN Routing"]
        Gossip["Gossipsub<br/>📢 Pheromone Broadcast"]
        Relay["Relay Servers<br/>🔄 NAT Traversal"]
    end

    CLI --> NA
    NA <--> CA
    CA <--> AA
    CA --> Sled
    NA <--> mDNS
    NA <--> Kad
    NA <--> Gossip
    NA <-.-> Relay

The easiest way to see the swarm in action (requires Linux/Mac):

# Runs 5 nodes, primes the network, and starts generating traffic
./scripts/simulate_swarm.sh

Note: This simulates on one machine. For real devices (Pi, servers, IoT), see DEPLOYMENT.md.

# Clone and enter directory
git clone https://github.com/your-org/shop-protocol.git
cd shop-protocol/shop

# Start 1 bootnode + 4 workers
docker compose up --build -d

# View logs
docker compose logs -f bootnode

# Open Dashboard
open http://localhost:3000

# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/your-org/shop-protocol.git
cd shop-protocol/shop
cargo build --release

# Run a node
cargo run -p shop-cli -- --api-port 3000

# Run additional nodes (in separate terminals)
cargo run -p shop-cli -- --api-port 3001
cargo run -p shop-cli -- --api-port 3002

The quick start options above are for local testing. For deploying SHOP across real devices (Raspberry Pi, VPS, IoT devices, etc.), see:

📘 DEPLOYMENT.md - Comprehensive guide covering:

• ✅ Platform support (Linux, macOS, Windows, Raspberry Pi, Docker, Kubernetes)
• ✅ LAN vs WAN deployment strategies
• ✅ NAT traversal configuration
• ✅ Production readiness assessment
• ✅ Troubleshooting common issues
• ⚠️ Current limitations and gaps

TL;DR:

• LAN (Same Network): Just run the binary, nodes auto-discover via mDNS
• WAN (Internet): Need a bootnode with public IP + relay configuration
• Production: Use Docker with persistent volumes and structured logging

Example: Dispatch a Packet

curl -X POST http://localhost:3000/dispatch \
  -H "Content-Type: application/json" \
  -H "x-shop-token: shop-secret" \
  -d '{"destination": "12D3KooW...", "payload": "hello"}'

shop/
├── crates/
│   ├── shop-cli/       # CLI entry point
│   ├── shop-node/      # Core node (actors, API, storage)
│   ├── shop-core/      # Shared types and math
│   └── shop-proto/     # Protobuf definitions
├── Dockerfile          # Multi-stage production build
├── docker-compose.yml  # 5-node deployment
└── scripts/            # Simulation utilities

• Bio-Engine with PID-tuned evaporation
• Hybrid mDNS/DHT discovery
• Persistent identity and graph state
• Security hardening (auth, DoS protection)
• Docker deployment

• 🌐 WAN Connectivity — NAT traversal via Circuit Relay v2 + DCUtR hole punching
• 🔍 AutoNAT — Automatic NAT status detection

• 🛡️ Stability Hardening — Deadlock prevention, graph pruning, Monitor Pattern
• 🔄 Fail-Fast Actors — JoinHandle tracking triggers shutdown on panic

• 🏁 Multi-Colony Competition — Red vs Blue foraging strategies
• 🔌 WASM Plugins — Hot-swap foraging logic at runtime
• 📊 Prometheus Metrics — Production observability

MIT License — see LICENSE for details.

Built with 🦀 Rust and inspired by 🐜 Nature