Nyumbani Mesh

Nyumbani Mesh - A Peer-to-Peer, Zero-Configuration, Content-Addressable Storage Network.

Problem Statement

In many African and global contexts, reliable and affordable internet connectivity can be a significant challenge. This often hinders efficient local data sharing, content distribution, and collaborative work, particularly in environments with limited or no access to centralized servers or cloud infrastructure. Existing solutions often require complex setup, constant internet access, or incur high data costs.

Nyumbani Mesh aims to solve the problem of localized, efficient, and resilient data sharing without reliance on centralized infrastructure or consistent internet connectivity.

Solution Overview

Nyumbani Mesh provides a robust, peer-to-peer network for local and wider-area data sharing. It allows devices to discover each other automatically, securely share file chunks, and maintain a distributed catalog of available content.

• Zero-Configuration Peer Discovery: Utilizes mDNS for automatic, plug-and-play node identification on local networks.
• Wider-Area Peer Discovery: Integrates Kademlia Distributed Hash Table (DHT) for discovering and connecting to peers beyond the local network, enabling a broader mesh.
• Content-Addressable Storage: Files are broken into encrypted chunks, hashed (SHA-256) for unique identification, and stored. This ensures data integrity, facilitates efficient deduplication, and allows for dynamic file reconstruction.
• Secure Data Handling: Implements AES-256 GCM encryption for all file chunks, ensuring data is secure at rest and in transit.
• Decentralized Data Sharing: Enables direct peer-to-peer data exchange without a central server, reducing bottlenecks and single points of failure.
• NAT Traversal: Employs STUN for public IP discovery and attempts UPnP/NAT-PMP for automatic port forwarding, enhancing peer accessibility across various network configurations.
• Rust-powered Reliability: Built with Rust for memory safety, concurrency, and high performance.
• Local-First Approach: Optimized for scenarios with limited internet access, promoting offline data availability and resilience.

The approach is unique because it combines mDNS for truly zero-config local discovery with a content-addressable storage model, making it ideal for resilient, self-organizing networks in diverse connectivity environments.

Demo

• Link to live demo

Technical Architecture

System Architecture

Component Overview

• nyumbani_core: The main application that orchestrates all components, exposes HTTP APIs, and manages the peer-to-peer network.
• nyumbani_discovery: Handles peer discovery using libp2p protocols (mDNS, Kademlia DHT), peer management, and event broadcasting.
• nyumbani_storage: Manages persistent storage of file chunks, manifests, posts, and peer information using the sled database.
• nyumbani_common: Contains shared types and utilities used across all modules (manifests, posts, peer tables).
• nyumbani-ui: Web-based user interface built with Svelte, providing visualization of network peers, files, and posts.

Data Flow

1. File Ingestion: User uploads a file through the web UI or API → File is chunked and encrypted → Chunks stored locally → FileManifest created and broadcast via gossipsub.
2. Peer Discovery: New nodes join the network → mDNS discovers local peers → DHT lookup for wider-area peers → Peer information stored and shared.
3. File Download: User requests a file → Application queries peers for chunks → Chunks downloaded in parallel → File reconstructed and decrypted → Saved locally.
4. Social Messaging: User creates a post → Post broadcast to all peers via gossipsub → All peers store post in local database.

High-level architecture diagram

Tech stack

• Language: Rust
• Networking: libp2p (with mDNS, Kademlia DHT, Gossipsub, Relay, AutoNAT, Identify, Ping), actix-web (for HTTP API), reqwest (HTTP client), local-ip-address (for local IP detection).
• Storage: sled (embedded key-value store), sha2 (SHA-256 hashing), sha3 (SHA3-256 for DHT keys), hex (hexadecimal encoding), aes-gcm (AES-256 GCM encryption).
• Concurrency: tokio (asynchronous runtime), async-trait for trait implementations.
• UI: Svelte 4 with Vite, TailwindCSS for the nyumbani-ui module, embedded into the Rust binary via rust-embed.
• Identity: ed25519-dalek (for node identity/signing).
• CLI: clap (command-line argument parsing).
• Serialization: serde, serde_json, bincode for various data formats.

Key technical decisions

• libp2p Framework: Migrated to libp2p for comprehensive peer-to-peer networking. This provides a unified protocol stack with support for multiple transport protocols, connection management, and interoperability with other libp2p-based projects.

• Kademlia DHT (via libp2p): Integrated as part of libp2p for robust distributed hash table functionality, enabling peers to discover each other across wider areas and efficiently route queries.

• Gossipsub Protocol: Implemented for publish-subscribe messaging, allowing nodes to subscribe to topics (e.g., manifests) and receive broadcasts efficiently across the mesh without central coordination.

• Relay Protocol: Enables NAT traversal by allowing peers behind symmetric NATs to relay connections through intermediate peers, significantly improving network connectivity.

• mDNS (via libp2p): Maintains local network peer discovery capabilities, automatically discovering nodes on the same local network without configuration.

• Content-Addressable Storage with Encryption: By hashing file chunks (SHA-256) and using these hashes as keys, we ensure data integrity and facilitate deduplication. AES-256 GCM encryption on chunks provides strong security for data at rest and in transit.

• Sled Database: An embedded key-value store chosen for its performance, durability, and ease of integration directly within the Rust application, suitable for local, decentralized storage of chunks, manifests, peers, and posts.

• File Chunking & Reconstruction: Files are split into fixed-size chunks during ingestion, enabling efficient partial downloads and deduplication across the network.

• Distributed File Manifests: A system where FileManifest objects, containing ordered chunk hashes and metadata, are discoverable and transferable across peers, allowing for dynamic file reconstruction from available network chunks.

• Gossipsub-based Manifest Broadcasting: File manifests are broadcast over the gossipsub topic nyumbani/manifests, enabling all nodes to maintain awareness of available files without centralized coordination.

• Post-based Social Layer: The mesh includes a social messaging system supporting chat messages and file requests, broadcasted across all peers to enable community interaction and resource discovery.

Installation & Setup

Prerequisites

• Rust (latest stable version recommended)

Step-by-step installation instructions

1. Clone the repository:

   git clone https://github.com/your-username/nyumbani-mesh.git
   cd nyumbani-mesh

2. Build the project:

   cargo build --release

3. Build the UI (if you modified it):

   cd nyumbani-ui
   bun install  # or npm install / yarn install
   bun run build
   cd ..

   This embeds the UI into the final binary.

4. Run the built binary:

   ./target/release/nyumbani_core --http-port 8080 --p2p-port 30333

Configuration details

Currently, configuration is minimal and primarily managed through environment variables or default settings. Future versions will include more detailed configuration options.

How to run the project locally

To run the main application with default settings:

cargo run --package nyumbani_core

This will start a Nyumbani Mesh node on http://127.0.0.1:8080 with P2P listening on port 30333.

With custom configuration:

cargo run --package nyumbani_core -- --http-port 8080 --p2p-port 30333 --db-path mesh_vault.db --identity-path node_identity.bin

CLI Arguments:

• --http-port <PORT>: HTTP API port (default: 8080)
• --p2p-port <PORT>: P2P listening port (default: 30333)
• --db-path <PATH>: Path to local database (default: mesh_vault.db)
• --identity-path <PATH>: Path to node identity file (default: node_identity.bin)
• --bootstrap-node <MULTIADDR>: Optional bootstrap peer multiaddress for initial network connection

Code examples

The nyumbani_core application exposes the following HTTP endpoints:

Core Endpoints:

• GET /api/status: Returns the node's unique ID and current status.
• GET /api/peers: Returns a JSON array of all currently discovered peers on the network.
• GET /api/chunks/{hash}: Attempts to retrieve a raw data chunk from the local storage using its SHA-256 hash.

File Management Endpoints:

• POST /api/ingest: Upload and ingest files into the mesh network. Files are automatically chunked and encrypted.
• POST /api/download: Download files from the mesh network by providing a file manifest.
• GET /api/manifests: Returns all local file manifests stored on the node.
• GET /api/catalog: Returns the global mesh catalog containing manifests from all discovered peers.

Social/Messaging Endpoints:

• GET /api/posts: Retrieve all posts (chat messages and file requests) from the mesh network.
• POST /api/posts: Create and broadcast a new post (chat message or file request) to all peers in the network.

Impact & Use Cases

Real-world applications

• Local File Sharing in Rural Areas: Facilitating data exchange in communities with limited or no internet access.
• Event and Conference Networking: Allowing attendees to share resources directly without relying on overloaded Wi-Fi.
• Emergency Communications: Providing resilient data transfer capabilities in disaster-struck regions where traditional infrastructure is down.
• Educational Institutions: Enabling students and teachers to share large files (e.g., videos, software) on campus networks efficiently.

Potential for scale

Nyumbani Mesh is designed for local network scalability. While not intended for global internet-scale distribution, its peer-to-peer nature allows for robust expansion within local subnets.

Technical Highlights

• Extensive Unit and Integration Tests: Ensuring reliability and correctness of core components.
• clippy and rustfmt: Adherence to Rust best practices and consistent code formatting.
• Strong Type System: Leveraging Rust's type system to prevent common programming errors at compile time.

Performance optimizations

• Zero-Copy Operations: Minimizing data copying where possible.
• Asynchronous I/O: Utilizing tokio for non-blocking network and disk operations.
• Efficient Hashing: Using SHA-256 for fast and secure content addressing.

Memory safety measures

Rust's ownership and borrowing system inherently prevents common memory safety bugs like null pointer dereferences, data races, and buffer overflows, making Nyumbani Mesh highly secure and stable.

Security considerations

• Data Integrity: Content-addressable storage (SHA-256 hashing of chunks and files) ensures that retrieved data matches the requested hash, preventing accidental or malicious alteration.
• Data Encryption: All file chunks are encrypted using AES-256 GCM with a unique, per-file encryption key, securing data both at rest (in local storage) and in transit (when shared between peers).
• Node Identity: Uses ED25519 for secure node identification, which can be extended for signing and authentication mechanisms.
• Local Network Focus: While featuring wider-area discovery, the primary mode of operation on local networks significantly reduces the attack surface from external threats.
• Future Enhancements: Access control mechanisms are planned for enhanced security.

Challenges & Solutions

Technical obstacles

• Reliable mDNS Discovery: Ensuring consistent peer discovery across various operating systems and network configurations.
  • Solution: Extensive testing and fine-tuning of mdns-sd integration, including handling service registration and browsing dynamically.
• Efficient Chunk Management: Storing and retrieving millions of small data chunks efficiently from the embedded database.
  • Solution: Optimized sled database schema and query patterns, leveraging its inherent performance characteristics.

Future Roadmap

Planned features

• Offline Manifest Synchronization: Mechanisms for nodes to exchange file manifests even when not directly connected, improving data availability.
• Access Control: Implement granular permissions for accessing files and resources within the mesh.
• Cross-Platform Binaries: Easier distribution with pre-compiled binaries for various OS.
• Enhanced Storage Optimization: Improved chunk deduplication and compression strategies.
• Web UI Enhancements: Additional dashboard features for monitoring network health and peer statistics.

Scalability plans

• DHT for Wide Area Networks: Kademlia DHT integration already provides the foundation for wider-area discovery and data routing, allowing peers to reach each other over the internet and potentially building a relay network. Further enhancements will focus on optimizing this for robust internet-scale operation.

Potential improvements

• Performance Benchmarking: Comprehensive performance testing and optimization for large-scale deployments.
• Monitoring & Observability: Built-in metrics and logging for network health monitoring.
• Advanced Routing: Improved peer routing strategies and connection optimization.
• Protocol Versioning: Version management for backward compatibility during protocol upgrades.

Team & Contributions

Philip Yaw Neequaye Ansah

Project Note

Built for the Rust Africa Hackathon 2026.

Focus area: Infrastructure & Connnectivity.

#RustAfricaHackathon

License & Acknowledgments

License: MIT License