{"id":31841563,"url":"https://github.com/dirvine/saorsa-gossip","last_synced_at":"2025-10-12T05:21:00.484Z","repository":{"id":318066700,"uuid":"1069811683","full_name":"dirvine/saorsa-gossip","owner":"dirvine","description":"PQC-secure gossip overlay network for Communitas","archived":false,"fork":false,"pushed_at":"2025-10-04T21:54:33.000Z","size":224,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T22:09:37.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dirvine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-04T17:07:05.000Z","updated_at":"2025-10-04T21:54:36.000Z","dependencies_parsed_at":"2025-10-04T22:09:41.562Z","dependency_job_id":"9c5749ee-a14f-4bcd-995d-ef12a2ab4de7","html_url":"https://github.com/dirvine/saorsa-gossip","commit_stats":null,"previous_names":["dirvine/saorsa-gossip"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dirvine/saorsa-gossip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-gossip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-gossip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-gossip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-gossip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dirvine","download_url":"https://codeload.github.com/dirvine/saorsa-gossip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirvine%2Fsaorsa-gossip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010341,"owners_count":26084738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-12T05:20:58.128Z","updated_at":"2025-10-12T05:21:00.466Z","avatar_url":"https://github.com/dirvine.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Saorsa Gossip Overlay\n\n[![CI](https://github.com/dirvine/saorsa-gossip/workflows/CI/badge.svg)](https://github.com/dirvine/saorsa-gossip/actions)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)\n[![Rust Version](https://img.shields.io/badge/rust-1.75%2B-blue.svg)](https://www.rust-lang.org)\n\n## 📦 Published Crates\n\n| Crate | Version | Docs | Downloads |\n|-------|---------|------|-----------|\n| [saorsa-gossip-types] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-types.svg)][types-crate] | [![Docs](https://docs.rs/saorsa-gossip-types/badge.svg)][types-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-types.svg)][types-crate] |\n| [saorsa-gossip-identity] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-identity.svg)][identity-crate] | [![Docs](https://docs.rs/saorsa-gossip-identity/badge.svg)][identity-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-identity.svg)][identity-crate] |\n| [saorsa-gossip-transport] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-transport.svg)][transport-crate] | [![Docs](https://docs.rs/saorsa-gossip-transport/badge.svg)][transport-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-transport.svg)][transport-crate] |\n| [saorsa-gossip-membership] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-membership.svg)][membership-crate] | [![Docs](https://docs.rs/saorsa-gossip-membership/badge.svg)][membership-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-membership.svg)][membership-crate] |\n| [saorsa-gossip-pubsub] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-pubsub.svg)][pubsub-crate] | [![Docs](https://docs.rs/saorsa-gossip-pubsub/badge.svg)][pubsub-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-pubsub.svg)][pubsub-crate] |\n| [saorsa-gossip-coordinator] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-coordinator.svg)][coordinator-crate] | [![Docs](https://docs.rs/saorsa-gossip-coordinator/badge.svg)][coordinator-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-coordinator.svg)][coordinator-crate] |\n| [saorsa-gossip-rendezvous] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-rendezvous.svg)][rendezvous-crate] | [![Docs](https://docs.rs/saorsa-gossip-rendezvous/badge.svg)][rendezvous-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-rendezvous.svg)][rendezvous-crate] |\n| [saorsa-gossip-groups] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-groups.svg)][groups-crate] | [![Docs](https://docs.rs/saorsa-gossip-groups/badge.svg)][groups-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-groups.svg)][groups-crate] |\n| [saorsa-gossip-presence] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-presence.svg)][presence-crate] | [![Docs](https://docs.rs/saorsa-gossip-presence/badge.svg)][presence-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-presence.svg)][presence-crate] |\n| [saorsa-gossip-crdt-sync] | [![Crates.io](https://img.shields.io/crates/v/saorsa-gossip-crdt-sync.svg)][crdt-crate] | [![Docs](https://docs.rs/saorsa-gossip-crdt-sync/badge.svg)][crdt-docs] | [![Downloads](https://img.shields.io/crates/d/saorsa-gossip-crdt-sync.svg)][crdt-crate] |\n\n[saorsa-gossip-types]: #core-crates\n[saorsa-gossip-identity]: #core-crates\n[saorsa-gossip-transport]: #core-crates\n[saorsa-gossip-membership]: #core-crates\n[saorsa-gossip-pubsub]: #core-crates\n[saorsa-gossip-coordinator]: #core-crates\n[saorsa-gossip-rendezvous]: #core-crates\n[saorsa-gossip-groups]: #core-crates\n[saorsa-gossip-presence]: #core-crates\n[saorsa-gossip-crdt-sync]: #core-crates\n\n[types-crate]: https://crates.io/crates/saorsa-gossip-types\n[types-docs]: https://docs.rs/saorsa-gossip-types\n[identity-crate]: https://crates.io/crates/saorsa-gossip-identity\n[identity-docs]: https://docs.rs/saorsa-gossip-identity\n[transport-crate]: https://crates.io/crates/saorsa-gossip-transport\n[transport-docs]: https://docs.rs/saorsa-gossip-transport\n[membership-crate]: https://crates.io/crates/saorsa-gossip-membership\n[membership-docs]: https://docs.rs/saorsa-gossip-membership\n[pubsub-crate]: https://crates.io/crates/saorsa-gossip-pubsub\n[pubsub-docs]: https://docs.rs/saorsa-gossip-pubsub\n[coordinator-crate]: https://crates.io/crates/saorsa-gossip-coordinator\n[coordinator-docs]: https://docs.rs/saorsa-gossip-coordinator\n[rendezvous-crate]: https://crates.io/crates/saorsa-gossip-rendezvous\n[rendezvous-docs]: https://docs.rs/saorsa-gossip-rendezvous\n[groups-crate]: https://crates.io/crates/saorsa-gossip-groups\n[groups-docs]: https://docs.rs/saorsa-gossip-groups\n[presence-crate]: https://crates.io/crates/saorsa-gossip-presence\n[presence-docs]: https://docs.rs/saorsa-gossip-presence\n[crdt-crate]: https://crates.io/crates/saorsa-gossip-crdt-sync\n[crdt-docs]: https://docs.rs/saorsa-gossip-crdt-sync\n\nA **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.\n\n## 🎯 Overview\n\nSaorsa Gossip implements a complete gossip overlay with:\n\n- **Post-Quantum Cryptography**: ML-KEM-768 + ML-DSA-65 + ChaCha20-Poly1305 (FIPS 203/204)\n- **QUIC Transport**: Low-latency, NAT-traversal with connection migration\n- **MLS Group Security**: RFC 9420 compliant end-to-end encryption with ChaCha20-Poly1305\n- **Gossip Protocols**: HyParView, SWIM, Plumtree for robust dissemination\n- **Local-First CRDTs**: Delta-CRDTs with anti-entropy synchronization\n- **No DHT**: Contact-graph-based discovery, no global directory\n\n**Status**: ✅ **Production-Ready v0.1.6** - Complete post-quantum cryptography, deployable coordinator binary, 192 tests passing, zero compilation warnings (see [DESIGN.md](DESIGN.md))\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                   Saorsa Gossip                         │\n│                                                         │\n│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌─────────┐ │\n│  │Presence │  │  PubSub  │  │  CRDT   │  │ Groups  │ │\n│  │(Beacons)│  │(Plumtree)│  │  Sync   │  │  (MLS)  │ │\n│  └────┬────┘  └─────┬────┘  └────┬────┘  └────┬────┘ │\n│       │             │            │            │       │\n│  ┌────┴─────────────┴────────────┴────────────┴────┐ │\n│  │            Membership Layer                      │ │\n│  │         (HyParView + SWIM)                       │ │\n│  └──────────────────┬───────────────────────────────┘ │\n│                     │                                  │\n│  ┌──────────────────┴───────────────────────────────┐ │\n│  │          Transport Layer (ant-quic)               │ │\n│  │   QUIC + PQC TLS 1.3 + NAT Traversal            │ │\n│  └──────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Core Crates\n\nAll crates are published on [crates.io](https://crates.io) at version **0.1.6** with production-ready post-quantum cryptography.\n\n| Crate | Purpose | Why It's Important |\n|-------|---------|-------------------|\n| [**types**](https://crates.io/crates/saorsa-gossip-types) | Core types (TopicId, PeerId, MessageHeader, wire formats) | **Foundation** - Defines all fundamental data structures and message formats used across the entire network. Includes BLAKE3-based message ID generation and CBOR wire serialization. |\n| [**identity**](https://crates.io/crates/saorsa-gossip-identity) | ML-DSA-65 key generation, signing, and verification | **Security Core** - Provides quantum-resistant digital signatures for all messages. Every peer identity is backed by ML-DSA-65 keypairs, ensuring authenticity in a post-quantum world. |\n| [**transport**](https://crates.io/crates/saorsa-gossip-transport) | QUIC transport with ant-quic, NAT traversal | **Network Layer** - Handles all peer-to-peer communication with low-latency QUIC streams. Includes hole-punching for NAT traversal and connection migration for mobile nodes. |\n| [**membership**](https://crates.io/crates/saorsa-gossip-membership) | HyParView partial views + SWIM failure detection | **Peer Discovery** - Maintains partial views of the network (8-12 active peers, 64-128 passive). SWIM detects failures in \u003c5s, HyParView heals partitions through periodic shuffles. Critical for network connectivity. |\n| [**pubsub**](https://crates.io/crates/saorsa-gossip-pubsub) | Plumtree epidemic broadcast with EAGER/IHAVE/IWANT | **Message Dissemination** - Efficiently broadcasts messages to all topic subscribers. Uses spanning tree (EAGER) for low latency and lazy links (IHAVE) for redundancy. Achieves \u003c500ms P50 broadcast latency. |\n| [**coordinator**](https://crates.io/crates/saorsa-gossip-coordinator) | Bootstrap node discovery, address reflection, relay | **Network Bootstrap** - Enables new peers to join the network. Publishes Coordinator Adverts (ML-DSA signed), provides FOAF (friends-of-friends) discovery, and optional relay services for NAT-restricted peers. |\n| [**rendezvous**](https://crates.io/crates/saorsa-gossip-rendezvous) | k=16 rendezvous sharding for global findability | **Global Discovery** - Implements 65,536 content-addressed shards (BLAKE3-based) for finding peers without DHTs. Providers publish signed summaries to deterministic shards, enabling discovery through capability queries. |\n| [**groups**](https://crates.io/crates/saorsa-gossip-groups) | MLS group key derivation with BLAKE3 KDF | **Group Security** - Wraps MLS (RFC 9420) for end-to-end encrypted group messaging. Derives presence beaconing secrets from MLS exporter contexts using BLAKE3 keyed hashing. Essential for private group communication. |\n| [**presence**](https://crates.io/crates/saorsa-gossip-presence) | MLS-derived beacon broadcasting, FOAF queries | **Online Detection** - Broadcasts encrypted presence beacons (10-15 min TTL) derived from group secrets. Enables \"who's online\" queries within groups and FOAF discovery (3-4 hop TTL). Privacy-preserving through MLS encryption. |\n| [**crdt-sync**](https://crates.io/crates/saorsa-gossip-crdt-sync) | Delta-CRDTs (OR-Set, LWW-Register) with anti-entropy | **Local-First Data** - Provides conflict-free replicated data types for distributed state. OR-Set tracks membership, LWW-Register for scalar values. Delta-based sync minimizes bandwidth. Anti-entropy every 30s ensures eventual consistency. |\n\n**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.\n\n## 🎮 Running a Test Network\n\nSaorsa Gossip provides two production-ready binaries for testing and deployment:\n\n### 📦 Deployable Binaries\n\n| Binary | Crate | Purpose |\n|--------|-------|---------|\n| `saorsa-gossip-coordinator` | [saorsa-coordinator](https://crates.io/crates/saorsa-coordinator) | Bootstrap/coordinator node for network discovery |\n| `saorsa-gossip` | [saorsa-gossip](https://crates.io/crates/saorsa-gossip) | CLI tool for testing all network features |\n\n### Installation\n\nInstall both binaries from crates.io:\n\n```bash\n# Install coordinator binary (provides saorsa-gossip-coordinator command)\ncargo install saorsa-coordinator\n\n# Install CLI tool (provides saorsa-gossip command)\ncargo install saorsa-gossip\n```\n\nOr build from source:\n\n```bash\n# Clone repository\ngit clone https://github.com/dirvine/saorsa-gossip.git\ncd saorsa-gossip\n\n# Build both binaries\ncargo build --release -p saorsa-coordinator -p saorsa-gossip\n\n# Binaries available at:\n# - target/release/saorsa-gossip-coordinator\n# - target/release/saorsa-gossip\n```\n\n### 🚀 Starting a Coordinator Node\n\nCoordinators provide bootstrap discovery for new peers joining the network:\n\n```bash\n# Start a coordinator on port 7000 with verbose logging\nsaorsa-gossip-coordinator \\\n  --verbose \\\n  --bind 0.0.0.0:7000 \\\n  --roles coordinator,reflector,relay \\\n  --publish-interval 60\n```\n\n**Options:**\n- `--bind \u003cADDR\u003e` - Address to bind to (default: `0.0.0.0:7000`)\n- `--roles \u003cROLES\u003e` - Comma-separated roles: `coordinator`, `reflector`, `relay`, `rendezvous`\n- `--publish-interval \u003cSECS\u003e` - Advert publish interval in seconds (default: 300)\n- `--identity-path \u003cPATH\u003e` - Path to ML-DSA identity file (default: `~/.saorsa-gossip/coordinator.identity`)\n- `--verbose` - Enable verbose DEBUG logging\n\n**Roles Explained:**\n- **coordinator**: Publishes signed coordinator adverts for bootstrap discovery\n- **reflector**: Provides address reflection for NAT traversal (observes peers' public IPs)\n- **relay**: Relays messages for NAT-restricted peers (optional, bandwidth-intensive)\n- **rendezvous**: Provides rendezvous sharding for global peer discovery (future)\n\n**What the coordinator does:**\n1. Generates or loads an ML-DSA-65 identity (32-byte PeerId)\n2. Publishes signed coordinator adverts every N seconds (~3.5KB CBOR messages)\n3. Provides address reflection for peers behind NAT\n4. Logs all activity with timestamps (INFO + DEBUG levels)\n\n**Example output:**\n```\nINFO Starting Saorsa Gossip Coordinator\nINFO Bind address: 0.0.0.0:7000\nINFO Roles: coordinator,reflector,relay\nINFO Loaded identity: c6333dcf4207a805989f9743e8b42d8e38ea35b085b2d54e80103f2c9725d41f\nINFO Coordinator advert publisher started (interval: 60s)\nDEBUG Published coordinator advert (3551 bytes)\n```\n\n### 🧪 Using the CLI Tool\n\nThe `saorsa-gossip` CLI exercises all library features:\n\n#### Identity Management\n\n```bash\n# Create a new ML-DSA identity\nsaorsa-gossip identity create --alias Alice\n\n# List all identities in keystore\nsaorsa-gossip identity list\n\n# Show identity details\nsaorsa-gossip identity show Alice\n\n# Delete an identity\nsaorsa-gossip identity delete Alice\n```\n\n**Output example:**\n```\n✓ Created identity: Alice\n  PeerId: e4338043f8a848e62110892ca8321f25fad745a615f9dd30f7515aba93988d7a\n  Saved to: /Users/you/.saorsa-gossip/keystore\n```\n\n#### Network Operations\n\n```bash\n# Join the gossip network via coordinator\nsaorsa-gossip network join \\\n  --coordinator 127.0.0.1:7000 \\\n  --identity Alice \\\n  --bind 0.0.0.0:0\n\n# Show network status\nsaorsa-gossip network status\n\n# List known peers\nsaorsa-gossip network peers\n```\n\n#### PubSub Messaging\n\n```bash\n# Subscribe to a topic\nsaorsa-gossip pubsub subscribe --topic news\n\n# Publish a message\nsaorsa-gossip pubsub publish --topic news --message \"Hello, gossip!\"\n\n# List subscriptions\nsaorsa-gossip pubsub list\n```\n\n#### Presence Beacons\n\n```bash\n# Start broadcasting presence\nsaorsa-gossip presence start --topic general\n\n# Check who's online\nsaorsa-gossip presence online --topic general\n\n# Stop broadcasting\nsaorsa-gossip presence stop --topic general\n```\n\n### 🌐 Local Test Network Setup\n\nRun a multi-node test network on your local machine:\n\n**Terminal 1 - Start Coordinator:**\n```bash\nsaorsa-coordinator --verbose --bind 127.0.0.1:7000 --roles coordinator,reflector --publish-interval 10\n```\n\n**Terminal 2 - Start Second Coordinator:**\n```bash\nsaorsa-coordinator --verbose --bind 127.0.0.1:7001 --roles coordinator,relay --publish-interval 15 \\\n  --identity-path ~/.saorsa-gossip/coordinator2.identity\n```\n\n**Terminal 3 - Create Test Identities:**\n```bash\n# Create 3 test node identities\nsaorsa-gossip identity create --alias Node1\nsaorsa-gossip identity create --alias Node2\nsaorsa-gossip identity create --alias Node3\n\n# Verify they were created\nsaorsa-gossip identity list\n```\n\n**What you'll see:**\n- **Coordinator 1 (port 7000)**: Publishing 3551-byte adverts every 10s with unique PeerId\n- **Coordinator 2 (port 7001)**: Publishing 3552-byte adverts every 15s with different PeerId\n- **CLI Tool**: Successfully creating ML-DSA identities and saving to keystore\n- **Persistence**: Coordinators remember their identities across restarts\n\n**Test Results from Local Validation:**\n- ✅ 2 coordinators ran simultaneously without conflicts\n- ✅ Identity persistence verified (same PeerId after restart)\n- ✅ Precise timing: 10s and 15s intervals maintained perfectly\n- ✅ Verbose logging showing all operations (INFO + DEBUG)\n- ✅ Zero compilation warnings, zero runtime errors\n\n### 📊 Logging and Monitoring\n\nAll binaries use structured logging with the `tracing` crate:\n\n**Log Levels:**\n- `INFO` - Operational events (startup, identity loading, service status)\n- `DEBUG` - Detailed activity (advert publications, message counts)\n\n**Enable verbose logging:**\n```bash\n# For coordinator\nsaorsa-coordinator --verbose ...\n\n# For CLI tool\nsaorsa-gossip --verbose identity create --alias Test\n```\n\n**Log format:**\n```\n2025-10-05T13:34:34.486139Z  INFO Starting Saorsa Gossip Coordinator\n2025-10-05T13:34:34.486960Z  INFO Loaded identity: c6333dcf...725d41f\n2025-10-05T13:34:34.488876Z DEBUG Published coordinator advert (3551 bytes)\n```\n\n### 🧪 Testing Checklist\n\nBefore deploying to production, verify:\n\n- [ ] Coordinator generates unique ML-DSA identity\n- [ ] Coordinator publishes adverts at configured interval\n- [ ] Identity persists across coordinator restarts (same PeerId)\n- [ ] Multiple coordinators can run on different ports\n- [ ] CLI can create and list identities\n- [ ] All logging shows timestamps and correct levels\n- [ ] No warnings or errors in logs\n\n### 🔍 Troubleshooting\n\n**Issue: \"Address already in use\"**\n- Another process is using the port\n- Solution: Use `--bind 127.0.0.1:PORT` with a different PORT\n\n**Issue: \"Failed to read keystore file\"**\n- Identity file doesn't exist yet (expected on first run)\n- Solution: Let the binary create it automatically\n\n**Issue: Coordinator not publishing adverts**\n- Check logs for ERROR messages\n- Verify `--roles` includes `coordinator`\n- Ensure `--publish-interval` is reasonable (\u003e5s)\n\n## 🚀 Quick Start (Library Usage)\n\n### Installation\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\nsaorsa-gossip-types = \"0.1.3\"\nsaorsa-gossip-identity = \"0.1.3\"\nsaorsa-gossip-transport = \"0.1.3\"\nsaorsa-gossip-membership = \"0.1.3\"\nsaorsa-gossip-pubsub = \"0.1.3\"\nsaorsa-gossip-coordinator = \"0.1.3\"\nsaorsa-gossip-rendezvous = \"0.1.3\"\nsaorsa-gossip-groups = \"0.1.3\"\nsaorsa-gossip-presence = \"0.1.3\"\nsaorsa-gossip-crdt-sync = \"0.1.3\"\n```\n\n### Basic Usage\n\n```rust\nuse saorsa_gossip_types::{TopicId, PeerId};\nuse saorsa_gossip_membership::{Membership, HyParViewMembership};\nuse saorsa_gossip_pubsub::{PubSub, PlumtreePubSub};\n\n#[tokio::main]\nasync fn main() -\u003e anyhow::Result\u003c()\u003e {\n    // Create a topic for your group\n    let topic = TopicId::new([1u8; 32]);\n\n    // Initialize membership layer\n    let membership = HyParViewMembership::default();\n    membership.join(vec![\"127.0.0.1:8080\".to_string()]).await?;\n\n    // Initialize pub/sub\n    let pubsub = PlumtreePubSub::new();\n    let mut rx = pubsub.subscribe(topic);\n\n    // Publish a message\n    pubsub.publish(topic, bytes::Bytes::from(\"Hello, gossip!\")).await?;\n\n    // Receive messages\n    while let Some((peer_id, data)) = rx.recv().await {\n        println!(\"Received from {}: {:?}\", peer_id, data);\n    }\n\n    Ok(())\n}\n```\n\n## 📚 Protocol Specifications\n\n### Membership (HyParView + SWIM)\n\n- **HyParView**: Partial views for connectivity\n  - Active view: 8-12 peers (routing)\n  - Passive view: 64-128 peers (healing)\n  - Periodic shuffle: every 30s\n\n- **SWIM**: Failure detection\n  - Probe interval: 1s\n  - Suspect timeout: 3s\n  - Piggyback membership deltas\n\n### Dissemination (Plumtree)\n\n- **EAGER** push along spanning tree\n- **IHAVE** digests to non-tree links (batch ≤ 1024)\n- **IWANT** pull on demand\n- **Anti-entropy**: every 30s with message-ID sketches\n- **Peer scoring**: mesh gating for quality\n\n### Presence \u0026 Discovery\n\n- **Beacons**: MLS exporter-derived tags, ML-DSA signed\n  - TTL: 10-15 minutes\n  - Encrypted to group with ChaCha20-Poly1305\n\n- **FOAF Queries**: Friends-of-friends discovery\n  - Fanout: 3\n  - TTL: 3-4 hops\n  - No DHT, no global directory\n\n### CRDTs\n\n- **OR-Set**: For membership tracking\n- **LWW-Register**: For scalar values\n- **Delta-CRDTs**: Bandwidth-efficient synchronization\n- **IBLT**: Reconciliation for large sets\n\n## 🔐 Security\n\n### Post-Quantum Cryptography\n\n- **ML-KEM-768**: Key encapsulation (FIPS 203)\n- **ML-DSA-65**: Digital signatures (FIPS 204) - default\n- **SLH-DSA**: Hash-based signatures (FIPS 205 / SPHINCS+) - available for long-term security\n  - 12 parameter sets: SHA2/SHAKE variants at 128/192/256-bit security\n  - Trade-offs: fast (larger sigs) vs small (smaller sigs)\n- **ChaCha20-Poly1305**: AEAD symmetric encryption (quantum-resistant)\n- **MLS**: Group messaging (RFC 9420)\n\nProvided by:\n- [`saorsa-pqc`](https://crates.io/crates/saorsa-pqc) v0.3.14+ - PQC primitives including ML-KEM, ML-DSA, SLH-DSA, and ChaCha20-Poly1305\n- [`saorsa-mls`](https://crates.io/crates/saorsa-mls) - MLS protocol\n\n### Threat Model\n\n| Attack | Mitigation |\n|--------|-----------|\n| Spam/Sybil | Invited joins, capability checks, scoring |\n| Eclipse | HyParView shuffles, passive diversity |\n| Replay | Per-topic nonces, signature checks, expiry |\n| Partition | Plumtree lazy links, anti-entropy |\n\n## 🛠️ Development\n\n### Building\n\n```bash\n# Build all crates\ncargo build --release\n\n# Run tests\ncargo test --all\n\n# Run with all features\ncargo build --all-features\n```\n\n### Testing\n\n```bash\n# Unit tests\ncargo test --all\n\n# Integration tests\ncargo test --test integration_tests\n\n# Performance benchmarks\ncargo bench --bench performance\n\n# Code coverage report\n./scripts/coverage.sh\n\n# Run all medium priority improvements\n./scripts/medium-priority-improvements.sh\n```\n\n### Code Quality\n\n```bash\n# Format code\ncargo fmt --all\n\n# Lint with Clippy (zero warnings enforced)\ncargo clippy --all-features --all-targets -- -D warnings\n\n# Generate documentation\ncargo doc --all-features --no-deps --open\n```\n\n## 📖 Documentation\n\n- [**SPEC.md**](SPEC.md) - Complete protocol specification\n- [**API Docs**](https://docs.rs/saorsa-gossip) - Rust API documentation\n- [**Examples**](examples/) - Usage examples (coming soon)\n\n### Crate Documentation\n\n- [saorsa-gossip-types](https://docs.rs/saorsa-gossip-types) - Core types and wire format\n- [saorsa-gossip-transport](https://docs.rs/saorsa-gossip-transport) - QUIC transport\n- [saorsa-gossip-membership](https://docs.rs/saorsa-gossip-membership) - HyParView + SWIM\n- [saorsa-gossip-pubsub](https://docs.rs/saorsa-gossip-pubsub) - Plumtree broadcast\n- [saorsa-gossip-presence](https://docs.rs/saorsa-gossip-presence) - Presence beacons\n- [saorsa-gossip-crdt-sync](https://docs.rs/saorsa-gossip-crdt-sync) - CRDT synchronization\n- [saorsa-gossip-groups](https://docs.rs/saorsa-gossip-groups) - MLS groups\n- [saorsa-gossip-identity](https://docs.rs/saorsa-gossip-identity) - Identity management\n\n## 🗺️ Roadmap\n\n### ✅ Phase 1: Foundation (Complete - v0.1.0)\n- [x] Core types and traits\n- [x] CRDT implementations (OR-Set, LWW)\n- [x] MLS group wrapper\n- [x] PQC identity management\n\n### ✅ Phase 2: Protocols (Complete - v0.1.2)\n- [x] HyParView trait definitions\n- [x] SWIM trait definitions\n- [x] Plumtree trait definitions\n- [x] Membership wired to transport\n- [x] Broadcast dissemination wired to transport\n- [x] Delta-CRDT anti-entropy\n\n### ✅ Phase 3: Transport (Complete - v0.1.2)\n- [x] ant-quic 0.10.1 QUIC integration\n- [x] NAT traversal with hole punching\n- [x] Ed25519 keypair generation\n- [x] Stream multiplexing (mship, pubsub, bulk)\n- [x] Message send/receive with routing\n\n### ✅ Phase 4: Production Crypto (Complete - v0.1.3)\n- [x] Real ML-DSA-65 message signing/verification\n- [x] BLAKE3 KDF for MLS exporter secrets\n- [x] Coordinator binary with full CLI\n- [x] Rendezvous shard implementation\n- [x] Zero compilation warnings\n- [x] 192 tests passing across all crates\n- [x] Published to crates.io\n\n### 📋 Phase 5: Advanced Features (In Progress)\n- [x] Presence beacon broadcasting (basic)\n- [x] FOAF query framework\n- [ ] Complete IBLT reconciliation\n- [ ] Peer scoring and mesh gating\n- [ ] Saorsa Sites (website publishing)\n- [ ] Complete anti-entropy with message sketches\n\n### 📋 Phase 6: Production Hardening (Planned)\n- [ ] 100-node test harness\n- [ ] Performance benchmarks\n- [ ] Security audit\n- [ ] Production deployment guide\n- [ ] Chaos engineering tests\n- [ ] Load testing framework\n\n## 📊 Performance Benchmarks\n\n### Transport Layer Performance (Real-World Results)\n\nComprehensive benchmarks on localhost (ant-quic 0.10.3 with direct stream acceptance):\n\n| Message Size | Throughput (Mbps) | Throughput (MB/s) | Latency | Notes |\n|--------------|-------------------|-------------------|---------|-------|\n| 1 KB | 281 | 33.5 | \u003c1ms | ✅ Low-latency messaging |\n| 10 KB | 2,759 | 328.9 | \u003c1ms | ✅ Optimal for small payloads |\n| 100 KB | 22,230 | 2,650 | \u003c10ms | 🚀 Excellent throughput |\n| 1 MB | 79,875 | 9,522 | ~10ms | 🚀🚀 Outstanding performance |\n| 10 MB | 1,471 | 175.4 | ~57ms | ✅ Sustained bulk transfer |\n| 50 MB | 1,392 | 166.0 | ~300ms | ✅ Large file transfer |\n| 100 MB | 1,400+ | 167+ | ~600ms | ✅ Consistent large transfers |\n\n**Test Environment:**\n- Platform: macOS Darwin 25.0.0\n- Network: Localhost (127.0.0.1)\n- Transport: QUIC with post-quantum TLS 1.3 (ML-DSA-65 signatures)\n- NAT Traversal: Enabled with hole-punching capability\n- Stream Type: Unidirectional (open_uni)\n- Encryption: ChaCha20-Poly1305 AEAD\n- Connection Time: 4ms (excellent)\n\n**Key Achievements:**\n- ✅ **Bidirectional data transfer working** - Direct stream acceptance implementation\n- ✅ **Zero timeout issues** - Continuous stream acceptance without 100ms limits\n- ✅ **Large message support** - Successfully transfers 100MB+ messages\n- ✅ **Consistent performance** - Stable throughput across message sizes\n- ✅ **Low latency** - Sub-millisecond for small messages, \u003c1s for 100MB\n\n**Technical Implementation:**\n- Direct connection access via `nat_endpoint.list_connections()`\n- Per-peer dedicated stream handlers (unidirectional + bidirectional)\n- 100MB read limit per stream (configurable)\n- Proper async/await handling with tokio runtime\n- Dynamic peer discovery without polling delays\n\n### Network Performance Targets\n\n| Metric | Target | Status |\n|--------|--------|--------|\n| Broadcast P50 latency | \u003c 500ms | 🔄 Testing |\n| Broadcast P95 latency | \u003c 2s | 🔄 Testing |\n| Failure detection | \u003c 5s | 🔄 Testing |\n| Memory per node | \u003c 50MB | 🔄 Testing |\n| Messages/sec/node | \u003e 100 | ✅ **Achieved** (\u003e2000 small msgs/sec) |\n| Transport latency | \u003c 10ms | ✅ **Achieved** (4ms connection, \u003c1ms for 1KB) |\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Priorities\n\n**High Priority** (blocking):\n1. Complete QUIC transport implementation\n2. Implement Plumtree EAGER/IHAVE/IWANT\n3. Implement proper message ID derivation\n\n**Medium Priority** (important):\n4. Complete HyParView join/shuffle\n5. Complete SWIM probe/suspect\n6. Add anti-entropy protocols\n\n**Low Priority** (enhancement):\n7. Performance optimization\n8. Comprehensive testing\n9. Example applications\n\n## 📜 License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## 🙏 Acknowledgments\n\nBuilt on top of:\n- [`ant-quic`](https://crates.io/crates/ant-quic) - QUIC transport with NAT traversal\n- [`saorsa-pqc`](https://crates.io/crates/saorsa-pqc) - Post-quantum cryptography\n- [`saorsa-mls`](https://crates.io/crates/saorsa-mls) - MLS group messaging\n\nInspired by:\n- **Plumtree** - Efficient epidemic broadcast\n- **HyParView** - Partial view membership protocol\n- **SWIM** - Scalable failure detection\n- **GossipSub** - Libp2p's gossip protocol\n\n## 📞 Contact\n\n- **Project**: [github.com/dirvine/saorsa-gossip](https://github.com/dirvine/saorsa-gossip)\n- **Issues**: [github.com/dirvine/saorsa-gossip/issues](https://github.com/dirvine/saorsa-gossip/issues)\n- **Author**: David Irvine ([@dirvine](https://github.com/dirvine))\n\n---\n\n**✅ 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.\n\n**Next Steps**: Advanced features (IBLT reconciliation, peer scoring), production hardening (security audit, 100-node testing), and Saorsa Sites implementation.\n\nSee [DESIGN.md](DESIGN.md) for the complete technical specification and implementation roadmap.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirvine%2Fsaorsa-gossip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirvine%2Fsaorsa-gossip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirvine%2Fsaorsa-gossip/lists"}