# Saorsa Core

[![CI](https://github.com/dirvine/saorsa-core-foundation/actions/workflows/rust.yml/badge.svg)](https://github.com/dirvine/saorsa-core-foundation/actions/workflows/rust.yml)
[![Crates.io](https://img.shields.io/crates/v/saorsa-core.svg)](https://crates.io/crates/saorsa-core)
[![Documentation](https://docs.rs/saorsa-core/badge.svg)](https://docs.rs/saorsa-core)

Core P2P networking library for Saorsa platform with DHT, QUIC transport, dual-stack endpoints (IPv6+IPv4), and four-word endpoint encoding.

## Documentation

- **API Reference**: see [docs/API.md](docs/API.md) - Comprehensive API documentation with examples
- **Architecture Decision Records**: see [docs/adr/](docs/adr/) - Design decisions and rationale
- **Security Model**: see [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md) - Network security and anti-Sybil protections
- **Auto-Upgrade System**: see [docs/AUTO_UPGRADE.md](docs/AUTO_UPGRADE.md) - Cross-platform binary updates
- Architecture overview: see [ARCHITECTURE.md](ARCHITECTURE.md)
- Contributor guide: see [AGENTS.md](AGENTS.md)

## Architecture Decision Records (ADRs)

Key design decisions are documented in [docs/adr/](docs/adr/):

| ADR | Title | Description |
|-----|-------|-------------|
| [ADR-001](docs/adr/ADR-001-multi-layer-architecture.md) | Multi-Layer P2P Architecture | Layered design separating transport, DHT, identity, and application concerns |
| [ADR-002](docs/adr/ADR-002-delegated-transport.md) | Delegated Transport | Using ant-quic for QUIC transport, NAT traversal, and bootstrap cache |
| [ADR-003](docs/adr/ADR-003-pure-post-quantum-crypto.md) | Pure Post-Quantum Cryptography | ML-DSA-65 and ML-KEM-768 without classical fallbacks |
| [ADR-004](docs/adr/ADR-004-four-word-addresses.md) | Four-Word Addresses | Human-readable addressing via word encoding |
| [ADR-005](docs/adr/ADR-005-skademlia-witness-protocol.md) | S/Kademlia Witness Protocol | Byzantine fault-tolerant DHT operations |
| [ADR-006](docs/adr/ADR-006-eigentrust-reputation.md) | EigenTrust Reputation | Iterative trust computation for Sybil resistance |
| [ADR-007](docs/adr/ADR-007-adaptive-networking.md) | Adaptive Networking | Machine learning for dynamic routing optimization |
| [ADR-008](docs/adr/ADR-008-bootstrap-delegation.md) | Bootstrap Cache Delegation | Delegating bootstrap to ant-quic with Sybil protection |
| [ADR-009](docs/adr/ADR-009-sybil-protection.md) | Sybil Protection | Multi-layered defense against identity attacks |
| [ADR-010](docs/adr/ADR-010-entangled-attestation.md) | Entangled Attestation | Software integrity verification via attestation chains |
| [ADR-011](docs/adr/ADR-011-geographic-placement.md) | Geographic Placement | Region-aware storage for regulatory compliance |
| [ADR-012](docs/adr/ADR-012-identity-without-pow.md) | Identity without PoW | Pure cryptographic identity using ML-DSA |

## Features

- **P2P NAT Traversal**: True peer-to-peer messaging with automatic NAT traversal (ant-quic 0.10.0+)
- **DHT (Distributed Hash Table)**: Advanced DHT implementation with RSPS (Root-Scoped Provider Summaries)
- **S/Kademlia Witness Protocol**: Byzantine fault tolerance with geographically diverse witness attestations
- **Placement System**: Intelligent shard placement with EigenTrust integration and Byzantine fault tolerance
- **QUIC Transport**: High-performance networking with ant-quic
- **Four-Word Endpoints**: Human‑readable network endpoints via `four-word-networking` (IPv4+port encodes to 4 words; decoding returns both IP and port; IPv6 word count decided by the crate).
- **Post-Quantum Cryptography**: Future-ready cryptographic algorithms
- **WebRTC over QUIC**: Advanced WebRTC-QUIC bridge for real-time media streaming with adaptive quality
- **Media Processing**: Image and audio processing with blurhash and symphonia
- **Geographic Routing**: Location-aware networking
- **Identity Management**: Post-quantum ML-DSA-65 signatures (NIST Level 3). No PoW; identities hold only required keys (no embedded word address).
- **Auto-Upgrade System**: Cross-platform binary updates with ML-DSA-65 signatures, rollback support, and configurable policies
- **Secure Storage**: Database persistence with deadpool-sqlite + rusqlite
- **Monitoring**: Prometheus metrics integration

## Quick Start

Add this to your `Cargo.toml`:

```toml
[dependencies]
saorsa-core = "0.5.0"
```

### Basic DHT Node

```rust
use saorsa_core::{Network, NetworkConfig, NodeId};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new network node
    let config = NetworkConfig::default();
    let mut network = Network::new(config).await?;
    
    // Start the network
    network.start().await?;
    
    // Store some data
    let key = b"example-key";
    let value = b"example-value";
    network.store(key, value.to_vec()).await?;
    
    // Retrieve the data
    if let Some(retrieved) = network.retrieve(key).await? {
        println!("Retrieved: {:?}", retrieved);
    }
    
    Ok(())
}
```

### P2P NAT Traversal

saorsa-core v0.5.0+ includes full P2P NAT traversal support, enabling direct peer-to-peer connections:

```rust
use saorsa_core::messaging::{MessagingService, NetworkConfig, DhtClient};
use saorsa_core::identity::FourWordAddress;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create two messaging service instances with P2P NAT traversal (default)
    let config = NetworkConfig::default();  // Includes P2P NAT traversal

    let service1 = MessagingService::new_with_config(
        FourWordAddress("peer-one-alpha".to_string()),
        DhtClient::new()?,
        config.clone(),
    ).await?;

    let service2 = MessagingService::new_with_config(
        FourWordAddress("peer-two-beta".to_string()),
        DhtClient::new()?,
        config,
    ).await?;

    // Connect peers directly
    let addr2 = service2.listen_addrs().await[0];
    service1.connect_peer(&addr2).await?;

    // Send P2P message
    service1.send_direct_message(&addr2, b"Hello P2P!").await?;

    Ok(())
}
```

**NAT Traversal Modes:**
- **P2P Node** (default): Both send and receive path validations for symmetric P2P connections
- **Client Only**: Outgoing connections only, minimal resource usage
- **Disabled**: No NAT traversal for private networks

**Configuration Examples:**
```rust
// Default P2P mode with concurrency limit of 10
let config = NetworkConfig::default();

// High-traffic P2P node
let config = NetworkConfig::p2p_node(50);

// Lightweight client
let config = NetworkConfig::client_only();

// Private network (no NAT traversal)
let config = NetworkConfig::no_nat_traversal();
```

### Four-Word Endpoints

- Endpoints are encoded/decoded using the `four-word-networking` crate's adaptive API.
- IPv4+port → 4 words; decoding returns both IP and port. IPv6 → word count is crate‑defined.
- Four‑words are reserved strictly for network endpoints; user identities in messaging are separate handles.

## Architecture

### Core Components

1. **Network Layer**: QUIC-based P2P networking with automatic NAT traversal (ant-quic 0.10.0+)
2. **DHT**: S/Kademlia-based DHT with RSPS optimization and witness attestations for Byzantine fault tolerance
3. **Placement System**: Intelligent shard placement with weighted selection algorithms
4. **Identity**: Post‑quantum cryptographic identities with ML‑DSA‑65 signatures (no PoW; no embedded four‑word address)
5. **Storage**: Local and distributed content storage with audit and repair
6. **Geographic Routing**: Location-aware message routing


### Cryptographic Architecture

Saorsa Core implements a pure post-quantum cryptographic approach for maximum security:

- **Post‑quantum signatures**: ML‑DSA‑65 (FIPS 204) for quantum‑resistant digital signatures (~128‑bit quantum security)
- **PQC Encryption**: ChaCha20-Poly1305 with quantum-resistant key derivation
- **Key Exchange**: ML-KEM-768 (FIPS 203) for quantum-resistant key encapsulation (~128-bit quantum security)
- **Hashing**: BLAKE3 for fast, secure content addressing
- **Transport Security**: QUIC with TLS 1.3 and PQC cipher suites
- **No Legacy Support**: Pure PQC implementation with no classical cryptographic fallbacks

### Recent Changes

- Removed all Proof‑of‑Work (PoW) usage (identity, adaptive, placement/DHT, error types, CLI).
- Adopted `four-word-networking` adaptive API; four‑words reserved for endpoints only.
- Implemented dual‑stack listeners (IPv6 + IPv4) and Happy Eyeballs dialing.
- Introduced `UserHandle` for messaging identities; migrated mentions, presence, participants, search, reactions, and read/delivered receipts to use it.

### Data Flow

```
Application
    ↓
Network API
    ↓
Placement Engine → DHT + Geographic Routing
    ↓              ↓
    ↓         Audit & Repair
    ↓              ↓
QUIC Transport (ant-quic)
    ↓
Internet
```

### Placement System

Saorsa Core includes an advanced placement system for optimal distribution of erasure-coded shards across the network:

```rust
use saorsa_core::placement::{
    PlacementEngine, PlacementConfig, GeographicLocation, NetworkRegion
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure placement system
    let config = PlacementConfig {
        replication_factor: (3, 8).into(), // Min 3, target 8 replicas
        byzantine_tolerance: 2.into(),      // Tolerate up to 2 Byzantine nodes
        placement_timeout: Duration::from_secs(30),
        geographic_diversity: true,
        weights: OptimizationWeights {
            trust_weight: 0.4,        // EigenTrust reputation
            performance_weight: 0.3,   // Node performance metrics
            capacity_weight: 0.2,      // Available storage capacity
            diversity_bonus: 0.1,      // Geographic/network diversity
        },
    };
    
    // Create placement engine
    let mut engine = PlacementEngine::new(config);
    
    // Place data with optimal shard distribution
    let data = b"important data to store";
    let decision = placement_orchestrator.place_data(
        data.to_vec(),
        8, // replication factor
        Some(NetworkRegion::NorthAmerica),
    ).await?;
    
    println!("Placed {} shards across {} nodes", 
             decision.shard_count, 
             decision.selected_nodes.len());
    
    Ok(())
}
```

#### Key Features

- **EigenTrust Integration**: Uses reputation scores for node selection
- **Weighted Selection**: Balances trust, performance, capacity, and diversity
- **Byzantine Fault Tolerance**: Configurable f-out-of-3f+1 security model
- **Geographic Diversity**: Ensures shards are distributed across regions
- **Continuous Monitoring**: Audit system with automatic repair
- **DHT Record Types**: Efficient ≤512B records with cryptographic validation
- **Hysteresis Control**: Prevents repair storms with smart cooldown

## Configuration

```rust
use saorsa_core::NetworkConfig;

let config = NetworkConfig {
    listen_port: 9000,
    bootstrap_nodes: vec![
        "bootstrap1.example.com:9000".parse()?,
        "bootstrap2.example.com:9000".parse()?,
    ],
    enable_four_word_addresses: true,
    dht_replication: 20,
    storage_capacity: 1024 * 1024 * 1024, // 1GB
    ..Default::default()
};
```

## Feature Flags

- `default` - Metrics and Prometheus integration
- `metrics` - Prometheus metrics and monitoring
- `mocks` - Test/dummy helpers for development (off by default)
- `h2_greedy` - Hyperbolic greedy routing helpers in API
- `test-utils` - Test utilities including mock DHT for integration tests
- `attestation` - Entangled Attestation system for software integrity verification

Note: DHT, ant-quic QUIC transport, and post-quantum cryptography are always enabled. Four-word networking is a core feature.

## Performance

Saorsa Core is designed for high performance:

- **Concurrent Operations**: Tokio-based async runtime
- **Memory Efficiency**: Zero-copy operations where possible
- **Network Optimization**: QUIC with congestion control
- **Caching**: Multi-level caching with Q-learning optimization

### Benchmarks

Run benchmarks with:

```bash
cargo bench
```

Key benchmarks:
- DHT operations: ~10,000 ops/sec
- Storage throughput: ~100 MB/sec
- Geographic routing: <10ms latency
- Placement decisions: <1s for 8-node selection
- Shard repair: Automatic with <1h detection
- Cryptographic operations: Hardware-accelerated

## Security

Saorsa Core implements defense-in-depth security designed for adversarial decentralized environments.

**For complete security documentation, see [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).**

### Cryptographic Foundation

- **Post-Quantum Signatures**: ML-DSA-65 (FIPS 204) for quantum-resistant digital signatures (~128-bit quantum security)
- **Key Exchange**: ML-KEM-768 (FIPS 203) for quantum-resistant key encapsulation
- **Symmetric Encryption**: ChaCha20-Poly1305 with quantum-resistant key derivation
- **Hashing**: BLAKE3 for fast, secure content addressing
- **Pure PQC**: No classical cryptographic fallbacks - quantum-resistant from the ground up

### Network Protection

| Protection | Implementation |
|------------|----------------|
| **Node Monitoring** | Automatic eviction after 3 consecutive failures |
| **Reputation System** | EigenTrust++ with multi-factor trust scoring |
| **Sybil Resistance** | IP diversity limits (/64: 1, /48: 3, /32: 10, ASN: 20) |
| **Geographic Diversity** | Minimum 3 regions for witness quorum |
| **Byzantine Tolerance** | f=2 in 3f+1 model (5 of 7 witnesses required) |
| **Data Verification** | Nonce-based attestation: BLAKE3(nonce || data) |
| **Entangled Attestation** | Software integrity via EntangledId (Phase 1: soft enforcement) |

### Entangled Attestation (Phase 1)

The Entangled Attestation system ensures nodes are running authorized software without relying on centralized authorities or proprietary hardware. A node's identity becomes mathematically "entangled" with its software:

```
EntangledId = BLAKE3(public_key || binary_hash || nonce)
```

**Key Properties:**
- **Software Binding**: Any modification to the binary forces a change in identity
- **Reputation Loss**: Attackers cannot maintain reputation while running malicious code
- **No Hardware Trust**: Pure cryptographic verification without TPM/SGX requirements
- **Graceful Migration**: Phase 1 uses soft enforcement (warnings only) for network adoption

**Enforcement Modes:**
- `Off`: Attestation disabled (development/testing)
- `Soft`: Invalid attestations logged but connections allowed (Phase 1)
- `Hard`: Invalid attestations rejected (future phases)

**Roadmap:**
- Phase 1: Entangled Identity ✓ (current)
- Phase 2: Core Logic Extraction (saorsa-logic no_std crate)
- Phase 3: zkVM Integration (SP1 proofs)
- Phase 4: VDF Heartbeats (continuous execution proofs)

### Anti-Centralization

The network enforces geographic and infrastructure diversity to prevent centralization:

```
┌───────────────────────────────────────────────────┐
│           Geographic Witness Distribution          │
├───────────────────────────────────────────────────┤
│  Region A      Region B      Region C      ...    │
│  (max 2)       (max 2)       (max 2)              │
│     │             │             │                 │
│     └─────────────┼─────────────┘                 │
│                   ▼                               │
│        Quorum requires 3+ regions                 │
│        (prevents regional collusion)              │
└───────────────────────────────────────────────────┘
```

- **ASN Diversity**: Max 20 nodes per autonomous system
- **Hosting Provider Limits**: Stricter limits (halved) for known VPS/cloud providers
- **Eclipse Detection**: Continuous routing table diversity monitoring

## S/Kademlia Witness Protocol

Saorsa Core implements an advanced **S/Kademlia witness system** for Byzantine fault tolerance in DHT operations. This system ensures data integrity and prevents malicious nodes from corrupting stored data through cryptographically attested operations.

### Overview

The witness protocol requires multiple independent nodes to cryptographically attest to DHT operations before they are considered valid. This prevents:

- **Sybil Attacks**: Attackers cannot flood the network with fake identities
- **Eclipse Attacks**: Honest nodes cannot be isolated from the network
- **Data Corruption**: Malicious nodes cannot unilaterally modify stored data
- **Routing Manipulation**: Path selection cannot be influenced by adversaries

### Geographic Diversity (GeoIP Integration)

A key innovation in our witness protocol is **geographic diversity enforcement** using GeoIP data. Witnesses are selected to be geographically distributed, providing:

#### Anti-Collusion Guarantees
```
┌─────────────────────────────────────────────────────────┐
│                 Geographic Witness Selection             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   Region A          Region B          Region C          │
│   ┌────────┐        ┌────────┐        ┌────────┐        │
│   │Witness1│        │Witness2│        │Witness3│        │
│   │  EU    │        │  APAC  │        │   NA   │        │
│   └───┬────┘        └───┬────┘        └───┬────┘        │
│       │                 │                 │             │
│       └────────────┬────┴─────────────────┘             │
│                    │                                    │
│              Attestation Quorum                         │
│         (Geographic spread prevents                     │
│          regional collusion)                            │
└─────────────────────────────────────────────────────────┘
```

- **Regional Distribution**: Witnesses must come from different geographic regions
- **Latency Zones**: Selection considers network latency for optimal performance
- **Jurisdiction Diversity**: Data is attested across legal jurisdictions
- **Infrastructure Independence**: Reduces risk of correlated failures

#### Selection Algorithm

```rust
use saorsa_core::dht::witness::{WitnessSelector, GeographicConfig};

// Configure witness selection with geographic constraints
let config = GeographicConfig {
    min_regions: 3,           // Minimum distinct regions
    max_per_region: 2,        // Maximum witnesses per region
    prefer_low_latency: true, // Optimize for performance
    exclude_same_asn: true,   // Avoid same network provider
};

let selector = WitnessSelector::with_geographic_config(config);

// Select geographically diverse witnesses for a DHT key
let witnesses = selector.select_witnesses(
    &key,
    required_count,
    &candidate_nodes,
).await?;
```

### Cryptographic Attestation

Each witness signs attestations using **ML-DSA-65** post-quantum signatures:

```rust
use saorsa_core::dht::witness::{WitnessSigner, Attestation};

// Create a witness attestation
let attestation = Attestation {
    operation_id: operation.id(),
    key: key.clone(),
    value_hash: blake3::hash(&value),
    witness_id: my_node_id,
    timestamp: SystemTime::now(),
    geographic_region: my_region,
};

// Sign with ML-DSA-65 (post-quantum secure)
let signed = signer.sign_attestation(&attestation).await?;
```

### Verification Protocol

```rust
use saorsa_core::dht::witness::WitnessVerifier;

// Verify a quorum of witness attestations
let verifier = WitnessVerifier::new(trust_provider);

// Verify attestations meet quorum requirements
let result = verifier.verify_quorum(
    &attestations,
    required_quorum,      // e.g., 2/3 of witnesses
    geographic_diversity, // require regional spread
).await?;

match result {
    QuorumResult::Valid => {
        // Operation is valid, proceed
    }
    QuorumResult::InsufficientWitnesses => {
        // Not enough attestations, retry
    }
    QuorumResult::GeographicViolation => {
        // Witnesses too concentrated, reselect
    }
    QuorumResult::InvalidSignatures => {
        // Cryptographic verification failed
    }
}
```

### Security Properties

| Property | Guarantee |
|----------|-----------|
| **Byzantine Tolerance** | Tolerates f malicious nodes in 3f+1 system |
| **Geographic Spread** | Minimum 3 distinct regions for attestation |
| **Post-Quantum Security** | ML-DSA-65 signatures (NIST Level 3) |
| **Sybil Resistance** | Geographic diversity prevents identity flooding |
| **Forward Secrecy** | Each operation uses unique attestation context |
| **Non-Repudiation** | Signed attestations provide audit trail |

### Integration with EigenTrust

Witness behavior feeds into the EigenTrust reputation system:

```rust
// Witness performance affects trust scores
trust_provider.record_witness_behavior(
    witness_id,
    WitnessBehavior::ValidAttestation,
);

// Low-trust nodes are excluded from witness selection
let eligible_witnesses = candidates
    .iter()
    .filter(|n| trust_provider.get_trust(&n.id) > MIN_WITNESS_TRUST)
    .collect();
```

### Performance Considerations

- **Parallel Verification**: Attestations verified concurrently
- **Caching**: Valid attestations cached to reduce verification overhead
- **Batching**: Multiple operations can share witness quorums
- **Adaptive Selection**: Witness count adjusts based on data importance

## WebRTC over QUIC Integration

Saorsa Core provides a unique **WebRTC-over-QUIC bridge** that combines the real-time capabilities of WebRTC with the performance and reliability of QUIC transport. This allows for high-quality media streaming with improved NAT traversal and congestion control.

### Key Features

- **Seamless Integration**: Bridge WebRTC media streams over ant-quic transport
- **Adaptive Quality**: Automatic bandwidth and quality adaptation based on network conditions
- **Multiple Stream Types**: Support for audio, video, screen sharing, and data channels
- **QoS Management**: Intelligent Quality of Service with stream prioritization
- **Jitter Buffering**: Built-in jitter buffers for smooth media playback
- **Performance Monitoring**: Real-time statistics and performance metrics

### Basic WebRTC-QUIC Bridge Setup

```rust
use saorsa_core::messaging::{
    WebRtcQuicBridge, QuicMediaStreamManager, StreamConfig, StreamType, QosParameters
};
use saorsa_core::transport::ant_quic_adapter::P2PNetworkNode;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create network node
    let node = Arc::new(P2PNetworkNode::new("127.0.0.1:0".parse()?).await?);
    
    // Create WebRTC-QUIC bridge
    let bridge = WebRtcQuicBridge::new(node).await?;
    
    // Create stream manager for bandwidth management
    let manager = QuicMediaStreamManager::new(2000); // 2 Mbps
    manager.start_background_tasks().await?;
    
    // Connect to peer
    let peer_addr = "192.168.1.100:9000".parse()?;
    let peer_id = bridge.connect_peer(peer_addr).await?;
    
    // Configure audio stream
    let audio_config = StreamConfig {
        stream_type: StreamType::Audio,
        codec: "opus".to_string(),
        bitrate_kbps: 64,
        sample_rate: Some(48000),
        resolution: None,
    };
    bridge.add_stream(peer_id, StreamType::Audio, audio_config).await?;
    
    // Configure video stream
    let video_config = StreamConfig {
        stream_type: StreamType::Video,
        codec: "h264".to_string(),
        bitrate_kbps: 1000,
        sample_rate: None,
        resolution: Some((1280, 720)),
    };
    bridge.add_stream(peer_id, StreamType::Video, video_config).await?;
    
    // Set QoS parameters
    manager.set_qos_params(StreamType::Audio, QosParameters::audio()).await;
    manager.set_qos_params(StreamType::Video, QosParameters::video()).await;
    
    // Start receiving packets
    let mut receiver = bridge.start_receiving().await?;
    
    // Handle incoming packets
    tokio::spawn(async move {
        while let Some((peer_id, packet)) = receiver.recv().await {
            println!("Received {} packet from {}", packet.stream_type, peer_id);
            // Process packet...
        }
    });
    
    Ok(())
}
```

### Media Streaming Example

```rust
use saorsa_core::messaging::RtpPacket;

// Create and send RTP packets
async fn send_media_packets(
    bridge: &WebRtcQuicBridge,
    peer_id: PeerId,
) -> Result<()> {
    // Audio packet (Opus codec)
    let audio_packet = RtpPacket::new(
        96,                    // Payload type (Opus)
        1001,                  // Sequence number
        48000,                 // Timestamp (48kHz sample rate)
        0x12345678,            // SSRC identifier
        vec![0xAA; 160],       // Opus frame data (20ms @ 48kHz)
        StreamType::Audio,
    );
    bridge.send_rtp_packet(peer_id, audio_packet).await?;
    
    // Video packet (H.264 codec)
    let video_packet = RtpPacket::new(
        97,                    // Payload type (H.264)
        2001,                  // Sequence number
        90000,                 // Timestamp (90kHz for video)
        0x87654321,            // SSRC identifier
        vec![0xBB; 1200],      // H.264 NAL unit
        StreamType::Video,
    );
    bridge.send_rtp_packet(peer_id, video_packet).await?;
    
    Ok(())
}
```

### Quality of Service (QoS) Configuration

```rust
use saorsa_core::messaging::QosParameters;

// Configure QoS for different stream types
let audio_qos = QosParameters {
    priority: 3,           // Highest priority
    max_latency_ms: 20,    // Low latency for real-time audio
    max_jitter_ms: 5,      // Minimal jitter tolerance
    target_bitrate_kbps: 64,
    max_bitrate_kbps: 128,
    min_bitrate_kbps: 32,
    loss_threshold: 1.0,   // 1% packet loss threshold
};

let video_qos = QosParameters {
    priority: 2,           // Medium priority
    max_latency_ms: 100,   // Higher latency tolerance
    max_jitter_ms: 20,     // More jitter tolerance
    target_bitrate_kbps: 1000,
    max_bitrate_kbps: 2000,
    min_bitrate_kbps: 200,
    loss_threshold: 3.0,   // 3% packet loss threshold
};

manager.set_qos_params(StreamType::Audio, audio_qos).await;
manager.set_qos_params(StreamType::Video, video_qos).await;
```

### Bandwidth Adaptation

```rust
// Check for bandwidth adaptation recommendations
if let Some(adjustment) = manager.check_bandwidth_adaptation().await {
    match adjustment {
        BandwidthAdjustment::Increase { current, recommended } => {
            println!("Increase bandwidth: {} -> {} kbps", current, recommended);
            // Adjust encoder settings...
        }
        BandwidthAdjustment::Decrease { current, recommended } => {
            println!("Decrease bandwidth: {} -> {} kbps", current, recommended);
            // Reduce quality or bitrate...
        }
    }
}

// Check transmission capacity
let can_send_hd = manager.can_transmit(1500).await; // 1.5KB HD frame
if !can_send_hd {
    // Switch to lower resolution or quality
}
```

### Performance Monitoring

```rust
// Get peer statistics
if let Some(stats) = bridge.get_peer_stats(peer_id).await {
    println!("Packets sent: {}", stats.packets_sent);
    println!("Packets received: {}", stats.packets_received);
    println!("Bytes transferred: {}", stats.bytes_sent);
    println!("Active streams: {}", stats.streams.len());
}

// Get stream-specific statistics
let stream_stats = manager.get_all_stats().await;
for ((peer_id, stream_type), stats) in stream_stats {
    println!("{:?} stream to {}:", stream_type, peer_id);
    println!("  RTT: {}ms", stats.rtt_ms);
    println!("  Loss: {:.2}%", stats.loss_percentage());
    println!("  Throughput: {} kbps", stats.effective_bitrate_kbps());
}
```

### Advanced Features

#### Multi-Stream Management
```rust
// Configure multiple streams for comprehensive communication
bridge.add_stream(peer_id, StreamType::Audio, audio_config).await?;
bridge.add_stream(peer_id, StreamType::Video, video_config).await?;
bridge.add_stream(peer_id, StreamType::ScreenShare, screen_config).await?;
bridge.add_stream(peer_id, StreamType::Data, data_config).await?;
```

#### Custom Bridge Configuration
```rust
use saorsa_core::messaging::BridgeConfig;

let config = BridgeConfig {
    jitter_buffer_size: 100,                    // 100 packets max
    jitter_buffer_delay: Duration::from_millis(50), // 50ms buffer
    peer_timeout: Duration::from_secs(30),      // 30s peer timeout
    cleanup_interval: Duration::from_secs(5),   // Cleanup every 5s
    max_packet_size: 1500,                      // MTU consideration
    enable_adaptive_jitter: true,               // Adaptive jitter buffering
};

let bridge = WebRtcQuicBridge::new_with_config(node, config).await?;
```

#### Error Handling and Reconnection
```rust
// Robust error handling
match bridge.send_rtp_packet(peer_id, packet).await {
    Ok(_) => {
        // Packet sent successfully
    }
    Err(e) => {
        eprintln!("Failed to send packet: {}", e);
        
        // Attempt reconnection if peer disconnected
        if e.to_string().contains("not connected") {
            match bridge.connect_peer(peer_addr).await {
                Ok(new_peer_id) => {
                    // Reconfigure streams for new connection
                    configure_streams(&bridge, new_peer_id).await?;
                }
                Err(reconnect_err) => {
                    eprintln!("Reconnection failed: {}", reconnect_err);
                }
            }
        }
    }
}
```

### Use Cases

1. **Voice Calls**: Low-latency audio streaming with Opus codec
2. **Video Conferencing**: Adaptive video quality with H.264/VP8 codecs  
3. **Screen Sharing**: High-quality desktop streaming
4. **File Transfer**: Reliable data channel communication
5. **Gaming**: Real-time game state synchronization
6. **IoT Streaming**: Sensor data and telemetry transmission

## Media Processing

Built-in media processing capabilities:

- **Images**: JPEG, PNG, WebP, GIF support with blurhash
- **Audio**: Full codec support via symphonia
- **Streaming**: Real-time media streaming over WebRTC

## Database Integration

SQLite-based persistence with migrations:

```rust
use saorsa_core::storage::Database;

let db = Database::open("./data/node.db").await?;
db.store_message(&message).await?;
```

## Geographic Features

Location-aware networking:

- Geographic distance calculations
- Location-based routing
- Regional content distribution
- Privacy-preserving location services

## Development

### Building

```bash
# Standard build
cargo build --release

# With all features
cargo build --all-features

# Feature-specific build
cargo build --features "dht,quantum-resistant"
```

### Testing

```bash
# Unit tests
cargo test

# Integration tests
cargo test --test '*'

# Property-based tests
cargo test --features "proptest"
```

### Linting

```bash
cargo clippy --all-features -- -D warnings
cargo fmt --all
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

### Code Style

- Follow Rust 2024 idioms
- Use `cargo fmt` for formatting
- Ensure `cargo clippy` passes
- Add documentation for public APIs
- Include tests for all new features

## License

This project is dual-licensed:

- **AGPL-3.0**: Open source license for open source projects
- **Commercial**: Commercial license for proprietary projects

For commercial licensing, contact: david@saorsalabs.com

## Dependencies

### Core Dependencies
- `tokio` - Async runtime
- `futures` - Future utilities
- `serde` - Serialization
- `anyhow` - Error handling
- `tracing` - Logging

### Networking
- `ant-quic` (0.10.0+) - QUIC transport with P2P NAT traversal
- `four-word-networking` - Human-readable addresses
- `rustls` - TLS support

### Cryptography
- `saorsa-pqc` - Post-quantum cryptography (ML-DSA, ML-KEM, ChaCha20-Poly1305)
- `blake3` - Hashing
- `rand` - Random number generation

### Storage & Database
- `sqlx` - Database operations
- `lru` - LRU caching
- `reed-solomon-erasure` - Error correction

### Media & WebRTC
- `webrtc` - WebRTC implementation
- `image` - Image processing
- `symphonia` - Audio codecs
- `rodio` - Audio playback

See `Cargo.toml` for complete dependency list.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## Support

- **Issues**: [GitHub Issues](https://github.com/dirvine/saorsa-core-foundation/issues)
- **Discussions**: [GitHub Discussions](https://github.com/dirvine/saorsa-core-foundation/discussions)
- **Email**: david@saorsalabs.com

---

**Saorsa Labs Limited** - Building the decentralized future
