MeshService

A generic decentralized service layer for mesh networks. Build any peer-to-peer service following the Announce → Query → Response → Reserve pattern.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Application Services                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  FAPP   │  │ Housing │  │ Repair  │  │ Custom  │  ...   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       └────────────┴────────────┴────────────┘              │
│                    Service Layer (this crate)                │
│         ServiceMessage, ServiceRouter, Verification          │
│  ───────────────────────────────────────────────────────    │
│                     Mesh Layer                               │
│    (provided by quicprochat-p2p or other mesh impl)         │
└─────────────────────────────────────────────────────────────┘

Features

• Generic Protocol: Any service can be built on top (therapy appointments, housing, repairs, tutoring...)
• Ed25519 Signatures: All messages cryptographically signed
• Verification Framework: Multi-level trust (self-asserted, peer-endorsed, registry-verified)
• Efficient Wire Format: Fixed 64-byte header + CBOR payload
• Pluggable Handlers: Register custom services with the router
• Built-in Services: FAPP (psychotherapy) and Housing included

Quick Start

use meshservice::{
    capabilities,
    identity::ServiceIdentity,
    router::ServiceRouter,
    services::fapp::{FappService, SlotAnnounce, SlotQuery, Specialism, Modality},
};

// Create identity
let identity = ServiceIdentity::generate();

// Create router with FAPP service
let mut router = ServiceRouter::new(capabilities::RELAY);
router.register(Box::new(FappService::relay()));

// Therapist announces slots
let announce = SlotAnnounce::new(
    &[Specialism::CognitiveBehavioral],
    Modality::VideoCall,
    "104",  // Postal prefix
)
.with_slots(3)
.with_profile("https://therapists.de/dr-mueller");

let msg = meshservice::services::fapp::create_announce(&identity, &announce, 1)?;
router.handle(msg, Some(identity.public_key()))?;

// Patient queries
let query = SlotQuery::new(Specialism::CognitiveBehavioral, "104");
let query_msg = meshservice::services::fapp::create_query(&identity, &query)?;
let matches = router.query(&query_msg);

println!("Found {} therapists", matches.len());

Built-in Services

FAPP (Free Appointment Propagation Protocol)

Decentralized psychotherapy appointment discovery:

Service ID	Purpose
0x0001	Therapist slot announcements, patient queries

use meshservice::services::fapp::{SlotAnnounce, Specialism, Modality};

let announce = SlotAnnounce::new(
    &[Specialism::TraumaFocused, Specialism::CognitiveBehavioral],
    Modality::InPerson,
    "104",
)
.with_slots(2)
.with_profile("https://kbv.de/123");

Housing

Decentralized room/apartment sharing:

Service ID	Purpose
0x0002	Listing announcements, seeker queries

use meshservice::services::housing::{ListingAnnounce, ListingType, amenities};

let listing = ListingAnnounce::new(ListingType::Apartment, 65, 850, "104")
    .with_rooms(2)
    .with_amenities(amenities::FURNISHED | amenities::BALCONY);

Verification Framework

Three trust levels:

Level	Description	Example
0 - None	Bare announcement	Anonymous
1 - Self-Asserted	Profile URL provided	Website link
2 - Peer-Endorsed	Trusted peers vouch	Community rating
3 - Registry-Verified	Official registry	KBV license

use meshservice::verification::{Verification, TrustedVerifiers, VerificationLevel};

// Add trusted verifier
let mut verifiers = TrustedVerifiers::new();
verifiers.add(registry_public_key, "KBV Registry", VerificationLevel::RegistryVerified);
router.set_trusted_verifiers(verifiers);

// Require verification for announces
router.set_min_verification_level(2);

Wire Protocol

64-byte fixed header for efficient parsing:

 0-3   service_id (u32 LE)
 4     message_type (u8)
 5     version (u8)
 6-7   flags (reserved)
 8-23  message_id (16 bytes)
24-39  sender_address (16 bytes)
40-47  sequence (u64 LE)
48-49  ttl_hours (u16 LE)
50-57  timestamp (u64 LE)
58     hop_count (u8)
59     max_hops (u8)
60-63  payload_len (u32 LE)
---
64+    signature (64 bytes)
128+   payload (CBOR)
...    verifications (optional CBOR)

Building Custom Services

Implement ServiceHandler:

use meshservice::router::{ServiceHandler, ServiceAction, HandlerContext};

struct MyService;

impl ServiceHandler for MyService {
    fn service_id(&self) -> u32 { 0x8001 } // Custom range
    fn name(&self) -> &str { "MyService" }
    
    fn handle(&self, message: &ServiceMessage, ctx: &HandlerContext) 
        -> Result<ServiceAction, ServiceError> 
    {
        match message.message_type {
            MessageType::Announce => Ok(ServiceAction::StoreAndForward),
            MessageType::Query => {
                // Find matches, respond...
                Ok(ServiceAction::Handled)
            }
            _ => Ok(ServiceAction::Drop)
        }
    }
    
    fn matches_query(&self, announce: &StoredMessage, query: &ServiceMessage) -> bool {
        // Custom matching logic
        true
    }
}

Service IDs

ID	Service
0x0001	FAPP (Psychotherapy)
0x0002	Housing
0x0003	Repair
0x0004	Tutoring
0x0005	Medical
0x0006	Legal
0x0007	Volunteer
0x0008	Events
0x8000+	Custom/User-defined

Examples

# FAPP demo (therapist + patient)
cargo run --example fapp_service

# Housing demo (landlord + seeker)
cargo run --example housing_service

# Multi-service mesh
cargo run --example multi_service

Testing

cargo test

License

MIT