Saorsa Gossip Overlay

📦 Published Crates

Crate	Version	Docs	Downloads
saorsa-gossip-types
saorsa-gossip-identity
saorsa-gossip-transport
saorsa-gossip-membership
saorsa-gossip-pubsub
saorsa-gossip-coordinator
saorsa-gossip-rendezvous
saorsa-gossip-groups
saorsa-gossip-presence
saorsa-gossip-crdt-sync

A post-quantum secure gossip overlay network for decentralized peer-to-peer communication. Designed to replace DHT-based discovery with a contact-graph-aware gossip protocol, providing low-latency broadcast, partition tolerance, and quantum-resistant cryptography.

🎯 Overview

Saorsa Gossip implements a complete gossip overlay with:

• Post-Quantum Cryptography: ML-KEM-768 + ML-DSA-65 + ChaCha20-Poly1305 (FIPS 203/204)
• QUIC Transport: Low-latency, NAT-traversal with connection migration
• MLS Group Security: RFC 9420 compliant end-to-end encryption with ChaCha20-Poly1305
• Gossip Protocols: HyParView, SWIM, Plumtree for robust dissemination
• Local-First CRDTs: Delta-CRDTs with anti-entropy synchronization
• No DHT: Contact-graph-based discovery, no global directory

Status: ✅ Production-Ready v0.1.6 - Complete post-quantum cryptography, deployable coordinator binary, 192 tests passing, zero compilation warnings (see DESIGN.md)

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   Saorsa Gossip                         │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌─────────┐ │
│  │Presence │  │  PubSub  │  │  CRDT   │  │ Groups  │ │
│  │(Beacons)│  │(Plumtree)│  │  Sync   │  │  (MLS)  │ │
│  └────┬────┘  └─────┬────┘  └────┬────┘  └────┬────┘ │
│       │             │            │            │       │
│  ┌────┴─────────────┴────────────┴────────────┴────┐ │
│  │            Membership Layer                      │ │
│  │         (HyParView + SWIM)                       │ │
│  └──────────────────┬───────────────────────────────┘ │
│                     │                                  │
│  ┌──────────────────┴───────────────────────────────┐ │
│  │          Transport Layer (ant-quic)               │ │
│  │   QUIC + PQC TLS 1.3 + NAT Traversal            │ │
│  └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Core Crates

All crates are published on crates.io at version 0.1.6 with production-ready post-quantum cryptography.

Why these crates matter together: They form a complete decentralized gossip network stack - from quantum-resistant identities and QUIC transport, through membership and broadcast protocols, to group encryption and local-first data sync. No DHT, no central servers, pure peer-to-peer with post-quantum security.

🎮 Running a Test Network

Saorsa Gossip provides two production-ready binaries for testing and deployment:

📦 Deployable Binaries

Installation

Install both binaries from crates.io:

# Install coordinator binary (provides saorsa-gossip-coordinator command)
cargo install saorsa-coordinator

# Install CLI tool (provides saorsa-gossip command)
cargo install saorsa-gossip

Or build from source:

# Clone repository
git clone https://github.com/dirvine/saorsa-gossip.git
cd saorsa-gossip

# Build both binaries
cargo build --release -p saorsa-coordinator -p saorsa-gossip

# Binaries available at:
# - target/release/saorsa-gossip-coordinator
# - target/release/saorsa-gossip

🚀 Starting a Coordinator Node

Coordinators provide bootstrap discovery for new peers joining the network:

# Start a coordinator on port 7000 with verbose logging
saorsa-gossip-coordinator \
  --verbose \
  --bind 0.0.0.0:7000 \
  --roles coordinator,reflector,relay \
  --publish-interval 60

Options:

• --bind <ADDR> - Address to bind to (default: 0.0.0.0:7000)
• --roles <ROLES> - Comma-separated roles: coordinator, reflector, relay, rendezvous
• --publish-interval <SECS> - Advert publish interval in seconds (default: 300)
• --identity-path <PATH> - Path to ML-DSA identity file (default: ~/.saorsa-gossip/coordinator.identity)
• --verbose - Enable verbose DEBUG logging

Roles Explained:

• coordinator: Publishes signed coordinator adverts for bootstrap discovery
• reflector: Provides address reflection for NAT traversal (observes peers' public IPs)
• relay: Relays messages for NAT-restricted peers (optional, bandwidth-intensive)
• rendezvous: Provides rendezvous sharding for global peer discovery (future)

What the coordinator does:

1. Generates or loads an ML-DSA-65 identity (32-byte PeerId)
2. Publishes signed coordinator adverts every N seconds (~3.5KB CBOR messages)
3. Provides address reflection for peers behind NAT
4. Logs all activity with timestamps (INFO + DEBUG levels)

Example output:

INFO Starting Saorsa Gossip Coordinator
INFO Bind address: 0.0.0.0:7000
INFO Roles: coordinator,reflector,relay
INFO Loaded identity: c6333dcf4207a805989f9743e8b42d8e38ea35b085b2d54e80103f2c9725d41f
INFO Coordinator advert publisher started (interval: 60s)
DEBUG Published coordinator advert (3551 bytes)

🧪 Using the CLI Tool

The saorsa-gossip CLI exercises all library features:

Identity Management

# Create a new ML-DSA identity
saorsa-gossip identity create --alias Alice

# List all identities in keystore
saorsa-gossip identity list

# Show identity details
saorsa-gossip identity show Alice

# Delete an identity
saorsa-gossip identity delete Alice

Output example:

✓ Created identity: Alice
  PeerId: e4338043f8a848e62110892ca8321f25fad745a615f9dd30f7515aba93988d7a
  Saved to: /Users/you/.saorsa-gossip/keystore

Network Operations

# Join the gossip network via coordinator
saorsa-gossip network join \
  --coordinator 127.0.0.1:7000 \
  --identity Alice \
  --bind 0.0.0.0:0

# Show network status
saorsa-gossip network status

# List known peers
saorsa-gossip network peers

PubSub Messaging

# Subscribe to a topic
saorsa-gossip pubsub subscribe --topic news

# Publish a message
saorsa-gossip pubsub publish --topic news --message "Hello, gossip!"

# List subscriptions
saorsa-gossip pubsub list

Presence Beacons

# Start broadcasting presence
saorsa-gossip presence start --topic general

# Check who's online
saorsa-gossip presence online --topic general

# Stop broadcasting
saorsa-gossip presence stop --topic general

🌐 Local Test Network Setup

Run a multi-node test network on your local machine:

Terminal 1 - Start Coordinator:

saorsa-coordinator --verbose --bind 127.0.0.1:7000 --roles coordinator,reflector --publish-interval 10

Terminal 2 - Start Second Coordinator:

saorsa-coordinator --verbose --bind 127.0.0.1:7001 --roles coordinator,relay --publish-interval 15 \
  --identity-path ~/.saorsa-gossip/coordinator2.identity

Terminal 3 - Create Test Identities:

# Create 3 test node identities
saorsa-gossip identity create --alias Node1
saorsa-gossip identity create --alias Node2
saorsa-gossip identity create --alias Node3

# Verify they were created
saorsa-gossip identity list

What you'll see:

• Coordinator 1 (port 7000): Publishing 3551-byte adverts every 10s with unique PeerId
• Coordinator 2 (port 7001): Publishing 3552-byte adverts every 15s with different PeerId
• CLI Tool: Successfully creating ML-DSA identities and saving to keystore
• Persistence: Coordinators remember their identities across restarts

Test Results from Local Validation:

• ✅ 2 coordinators ran simultaneously without conflicts
• ✅ Identity persistence verified (same PeerId after restart)
• ✅ Precise timing: 10s and 15s intervals maintained perfectly
• ✅ Verbose logging showing all operations (INFO + DEBUG)
• ✅ Zero compilation warnings, zero runtime errors

📊 Logging and Monitoring

All binaries use structured logging with the tracing crate:

Log Levels:

• INFO - Operational events (startup, identity loading, service status)
• DEBUG - Detailed activity (advert publications, message counts)

Enable verbose logging:

# For coordinator
saorsa-coordinator --verbose ...

# For CLI tool
saorsa-gossip --verbose identity create --alias Test

Log format:

2025-10-05T13:34:34.486139Z  INFO Starting Saorsa Gossip Coordinator
2025-10-05T13:34:34.486960Z  INFO Loaded identity: c6333dcf...725d41f
2025-10-05T13:34:34.488876Z DEBUG Published coordinator advert (3551 bytes)

🧪 Testing Checklist

Before deploying to production, verify:

• Coordinator generates unique ML-DSA identity
• Coordinator publishes adverts at configured interval
• Identity persists across coordinator restarts (same PeerId)
• Multiple coordinators can run on different ports
• CLI can create and list identities
• All logging shows timestamps and correct levels
• No warnings or errors in logs

🔍 Troubleshooting

Issue: "Address already in use"

• Another process is using the port
• Solution: Use --bind 127.0.0.1:PORT with a different PORT

Issue: "Failed to read keystore file"

• Identity file doesn't exist yet (expected on first run)
• Solution: Let the binary create it automatically

Issue: Coordinator not publishing adverts

• Check logs for ERROR messages
• Verify --roles includes coordinator
• Ensure --publish-interval is reasonable (>5s)

🚀 Quick Start (Library Usage)

Installation

Add to your Cargo.toml:

[dependencies]
saorsa-gossip-types = "0.1.3"
saorsa-gossip-identity = "0.1.3"
saorsa-gossip-transport = "0.1.3"
saorsa-gossip-membership = "0.1.3"
saorsa-gossip-pubsub = "0.1.3"
saorsa-gossip-coordinator = "0.1.3"
saorsa-gossip-rendezvous = "0.1.3"
saorsa-gossip-groups = "0.1.3"
saorsa-gossip-presence = "0.1.3"
saorsa-gossip-crdt-sync = "0.1.3"

Basic Usage

use saorsa_gossip_types::{TopicId, PeerId};
use saorsa_gossip_membership::{Membership, HyParViewMembership};
use saorsa_gossip_pubsub::{PubSub, PlumtreePubSub};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a topic for your group
    let topic = TopicId::new([1u8; 32]);

    // Initialize membership layer
    let membership = HyParViewMembership::default();
    membership.join(vec!["127.0.0.1:8080".to_string()]).await?;

    // Initialize pub/sub
    let pubsub = PlumtreePubSub::new();
    let mut rx = pubsub.subscribe(topic);

    // Publish a message
    pubsub.publish(topic, bytes::Bytes::from("Hello, gossip!")).await?;

    // Receive messages
    while let Some((peer_id, data)) = rx.recv().await {
        println!("Received from {}: {:?}", peer_id, data);
    }

    Ok(())
}

📚 Protocol Specifications

Membership (HyParView + SWIM)

• HyParView: Partial views for connectivity

  • Active view: 8-12 peers (routing)
  • Passive view: 64-128 peers (healing)
  • Periodic shuffle: every 30s

• SWIM: Failure detection

  • Probe interval: 1s
  • Suspect timeout: 3s
  • Piggyback membership deltas

Dissemination (Plumtree)

• EAGER push along spanning tree
• IHAVE digests to non-tree links (batch ≤ 1024)
• IWANT pull on demand
• Anti-entropy: every 30s with message-ID sketches
• Peer scoring: mesh gating for quality

Presence & Discovery

• Beacons: MLS exporter-derived tags, ML-DSA signed

  • TTL: 10-15 minutes
  • Encrypted to group with ChaCha20-Poly1305

• FOAF Queries: Friends-of-friends discovery

  • Fanout: 3
  • TTL: 3-4 hops
  • No DHT, no global directory

CRDTs

• OR-Set: For membership tracking
• LWW-Register: For scalar values
• Delta-CRDTs: Bandwidth-efficient synchronization
• IBLT: Reconciliation for large sets

🔐 Security

Post-Quantum Cryptography

• ML-KEM-768: Key encapsulation (FIPS 203)
• ML-DSA-65: Digital signatures (FIPS 204) - default
• SLH-DSA: Hash-based signatures (FIPS 205 / SPHINCS+) - available for long-term security
  • 12 parameter sets: SHA2/SHAKE variants at 128/192/256-bit security
  • Trade-offs: fast (larger sigs) vs small (smaller sigs)
• ChaCha20-Poly1305: AEAD symmetric encryption (quantum-resistant)
• MLS: Group messaging (RFC 9420)

Provided by:

• saorsa-pqc v0.3.14+ - PQC primitives including ML-KEM, ML-DSA, SLH-DSA, and ChaCha20-Poly1305
• saorsa-mls - MLS protocol

Threat Model

🛠️ Development

Building

# Build all crates
cargo build --release

# Run tests
cargo test --all

# Run with all features
cargo build --all-features

Testing

# Unit tests
cargo test --all

# Integration tests
cargo test --test integration_tests

# Performance benchmarks
cargo bench --bench performance

# Code coverage report
./scripts/coverage.sh

# Run all medium priority improvements
./scripts/medium-priority-improvements.sh

Code Quality

# Format code
cargo fmt --all

# Lint with Clippy (zero warnings enforced)
cargo clippy --all-features --all-targets -- -D warnings

# Generate documentation
cargo doc --all-features --no-deps --open

📖 Documentation

• SPEC.md - Complete protocol specification
• API Docs - Rust API documentation
• Examples - Usage examples (coming soon)

Crate Documentation

• saorsa-gossip-types - Core types and wire format
• saorsa-gossip-transport - QUIC transport
• saorsa-gossip-membership - HyParView + SWIM
• saorsa-gossip-pubsub - Plumtree broadcast
• saorsa-gossip-presence - Presence beacons
• saorsa-gossip-crdt-sync - CRDT synchronization
• saorsa-gossip-groups - MLS groups
• saorsa-gossip-identity - Identity management

🗺️ Roadmap

✅ Phase 1: Foundation (Complete - v0.1.0)

• Core types and traits
• CRDT implementations (OR-Set, LWW)
• MLS group wrapper
• PQC identity management

✅ Phase 2: Protocols (Complete - v0.1.2)

• HyParView trait definitions
• SWIM trait definitions
• Plumtree trait definitions
• Membership wired to transport
• Broadcast dissemination wired to transport
• Delta-CRDT anti-entropy

✅ Phase 3: Transport (Complete - v0.1.2)

• ant-quic 0.10.1 QUIC integration
• NAT traversal with hole punching
• Ed25519 keypair generation
• Stream multiplexing (mship, pubsub, bulk)
• Message send/receive with routing

✅ Phase 4: Production Crypto (Complete - v0.1.3)

• Real ML-DSA-65 message signing/verification
• BLAKE3 KDF for MLS exporter secrets
• Coordinator binary with full CLI
• Rendezvous shard implementation
• Zero compilation warnings
• 192 tests passing across all crates
• Published to crates.io

📋 Phase 5: Advanced Features (In Progress)

• Presence beacon broadcasting (basic)
• FOAF query framework
• Complete IBLT reconciliation
• Peer scoring and mesh gating
• Saorsa Sites (website publishing)
• Complete anti-entropy with message sketches

📋 Phase 6: Production Hardening (Planned)

• 100-node test harness
• Performance benchmarks
• Security audit
• Production deployment guide
• Chaos engineering tests
• Load testing framework

📊 Performance Benchmarks

Transport Layer Performance (Real-World Results)

Comprehensive benchmarks on localhost (ant-quic 0.10.3 with direct stream acceptance):

Test Environment:

• Platform: macOS Darwin 25.0.0
• Network: Localhost (127.0.0.1)
• Transport: QUIC with post-quantum TLS 1.3 (ML-DSA-65 signatures)
• NAT Traversal: Enabled with hole-punching capability
• Stream Type: Unidirectional (open_uni)
• Encryption: ChaCha20-Poly1305 AEAD
• Connection Time: 4ms (excellent)

Key Achievements:

• ✅ Bidirectional data transfer working - Direct stream acceptance implementation
• ✅ Zero timeout issues - Continuous stream acceptance without 100ms limits
• ✅ Large message support - Successfully transfers 100MB+ messages
• ✅ Consistent performance - Stable throughput across message sizes
• ✅ Low latency - Sub-millisecond for small messages, <1s for 100MB

Technical Implementation:

• Direct connection access via nat_endpoint.list_connections()
• Per-peer dedicated stream handlers (unidirectional + bidirectional)
• 100MB read limit per stream (configurable)
• Proper async/await handling with tokio runtime
• Dynamic peer discovery without polling delays

Network Performance Targets

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Priorities

High Priority (blocking):

1. Complete QUIC transport implementation
2. Implement Plumtree EAGER/IHAVE/IWANT
3. Implement proper message ID derivation

Medium Priority (important): 4. Complete HyParView join/shuffle 5. Complete SWIM probe/suspect 6. Add anti-entropy protocols

Low Priority (enhancement): 7. Performance optimization 8. Comprehensive testing 9. Example applications

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

Built on top of:

• ant-quic - QUIC transport with NAT traversal
• saorsa-pqc - Post-quantum cryptography
• saorsa-mls - MLS group messaging

Inspired by:

• Plumtree - Efficient epidemic broadcast
• HyParView - Partial view membership protocol
• SWIM - Scalable failure detection
• GossipSub - Libp2p's gossip protocol

📞 Contact

• Project: github.com/dirvine/saorsa-gossip
• Issues: github.com/dirvine/saorsa-gossip/issues
• Author: David Irvine (@dirvine)

✅ Status v0.1.6: Production-ready foundation with complete post-quantum cryptography. Core gossip protocols implemented with real ML-DSA-65 signatures, BLAKE3 KDF, and deployable coordinator binary. All 192 tests passing with zero warnings. Published to crates.io.

Next Steps: Advanced features (IBLT reconciliation, peer scoring), production hardening (security audit, 100-node testing), and Saorsa Sites implementation.

See DESIGN.md for the complete technical specification and implementation roadmap.