saorsa-transport

Pure Post-Quantum QUIC transport with NAT traversal for P2P networks. Every node is symmetric - can connect AND accept connections.

Key Features

• 🔐 Pure Post-Quantum Cryptography (v0.2) - ML-KEM-768 + ML-DSA-65 ONLY - no classical fallback
• Symmetric P2P Nodes - Every node is identical: connect, accept, coordinate
• Automatic NAT Traversal - Per draft-seemann-quic-nat-traversal-02
• External Address Discovery - Per draft-ietf-quic-address-discovery-00
• Pure PQC Raw Public Keys - ML-DSA-65 authentication per our specification
• Zero Configuration Required - Sensible defaults, just create and connect
• Powered by saorsa-pqc - NIST FIPS 203/204 compliant implementations

Quick Start

use saorsa_transport::{P2pEndpoint, P2pConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a P2P endpoint - PQC is always on
    let config = P2pConfig::builder()
        .known_peer("peer.example.com:9000".parse()?)
        .build()?;

    let endpoint = P2pEndpoint::new(config).await?;
    println!("Peer ID: {:?}", endpoint.peer_id());

    // Connect to known peers for address discovery
    endpoint.connect_bootstrap().await?;

    // Your external address is now known
    if let Some(addr) = endpoint.external_address() {
        println!("External address: {}", addr);
    }

    Ok(())
}

Architecture

saorsa-transport uses a symmetric P2P model where every node has identical capabilities:

┌─────────────┐         ┌─────────────┐
│   Node A    │◄───────►│   Node B    │
│  (peer)     │   QUIC  │  (peer)     │
│             │   PQC   │             │
└─────────────┘         └─────────────┘
       │                       │
       │    OBSERVED_ADDRESS   │
       │◄──────────────────────┤
       │                       │
       ├──────────────────────►│
       │    ADD_ADDRESS        │
       └───────────────────────┘

No Roles - All Nodes Are Equal

In v0.13.0, we removed all role distinctions:

• No EndpointRole::Client/Server/Bootstrap
• No NatTraversalRole enum
• Any peer can coordinate NAT traversal for other peers
• Any peer can report your external address via OBSERVED_ADDRESS frames

The term "known_peers" replaces "bootstrap_nodes" - they're just addresses to connect to first. Any connected peer can help with address discovery.

Measure, don't trust: capability hints are treated as unverified signals. Peers are selected based on observed reachability and success rates, not self-asserted roles.

Three-Layer Design

1. Protocol Layer: QUIC + NAT traversal extension frames
2. Integration APIs: P2pEndpoint, P2pConfig
3. Applications: Binary, examples

Pure Post-Quantum Cryptography (v0.2)

saorsa-transport v0.2 uses PURE post-quantum cryptography - no classical algorithms, no hybrid modes, no fallback.

This is a greenfield network with no legacy compatibility requirements.

Algorithms

Algorithm	Standard	Purpose	Security Level	IANA Code
ML-KEM-768	FIPS 203	Key Exchange	NIST Level 3 (192-bit)	0x0201
ML-DSA-65	FIPS 204	Digital Signatures	NIST Level 3 (192-bit)	0x0905

Powered by saorsa-pqc

saorsa-transport uses saorsa-pqc for all PQC operations:

• NIST FIPS 203/204 compliant implementations
• AVX2/AVX-512/NEON hardware acceleration
• Constant-time operations for side-channel resistance
• Extensively tested against NIST Known Answer Tests (KATs)

use saorsa_transport::crypto::pqc::PqcConfig;

let pqc = PqcConfig::builder()
    .ml_kem(true)               // ML-KEM-768 key exchange
    .ml_dsa(true)               // ML-DSA-65 signatures
    .memory_pool_size(10)       // Memory pool for crypto ops
    .handshake_timeout_multiplier(2.0)  // PQC handshakes are larger
    .build()?;

Why Pure PQC (No Hybrid)?

• Greenfield Network - No legacy systems to maintain compatibility with
• Maximum Security - No weak classical algorithms in the chain
• Simpler Implementation - One cryptographic path, fewer edge cases
• Future-Proof - All connections quantum-resistant from day one
• NIST Standardized - ML-KEM and ML-DSA are FIPS 203/204 standards

Identity Model

• 32-byte PeerId - SHA-256 hash of ML-DSA-65 public key (compact identifier for addressing)
• ML-DSA-65 Authentication - All TLS handshake signatures use pure PQC
• ML-KEM-768 Key Exchange - All key agreement uses pure PQC

See docs/guides/pqc-security.md for security analysis.

NAT Traversal

NAT traversal is built into the QUIC protocol via extension frames, not STUN/TURN.

How It Works

1. Connect to any known peer
2. Peer observes your external address from incoming packets
3. Peer sends OBSERVED_ADDRESS frame back to you
4. You learn your public address and can coordinate hole punching
5. Direct P2P connection established through NAT

Extension Frames

Frame	Type ID	Purpose
ADD_ADDRESS	0x3d7e90 (IPv4), 0x3d7e91 (IPv6)	Advertise candidate addresses
PUNCH_ME_NOW	0x3d7e92 (IPv4), 0x3d7e93 (IPv6)	Coordinate hole punching timing
REMOVE_ADDRESS	0x3d7e94	Remove stale address
OBSERVED_ADDRESS	0x9f81a6 (IPv4), 0x9f81a7 (IPv6)	Report external address to peer

Transport Parameters

Parameter	ID	Purpose
NAT Traversal Capability	0x3d7e9f0bca12fea6	Negotiates NAT traversal support
RFC-Compliant Frames	0x3d7e9f0bca12fea8	Enables RFC frame format
Address Discovery	0x9f81a176	Configures address observation

NAT Type Support

NAT Type	Success Rate	Notes
Full Cone	>95%	Direct connection
Restricted Cone	80-90%	Coordinated punch
Port Restricted	70-85%	Port-specific coordination
Symmetric	60-80%	Prediction algorithms
CGNAT	50-70%	Relay fallback may be needed

See docs/NAT_TRAVERSAL_GUIDE.md for detailed information.

Raw Public Key Identity (v0.2)

Each node has a single ML-DSA-65 key pair for both identity and authentication:

// ML-DSA-65 keypair - used for everything
let (ml_dsa_pub, ml_dsa_sec) = generate_ml_dsa_65_keypair();

// PeerId = SHA-256(ML-DSA-65 public key) = 32 bytes
// Compact identifier for addressing and peer tracking
let peer_id = derive_peer_id_from_public_key(&ml_dsa_pub);

This follows our Pure PQC Authentication specification.

v0.2 Changes

• Pure PQC Identity: Single ML-DSA-65 key pair, no classical keys
• 32-byte PeerId: SHA-256 hash of ML-DSA-65 public key (1952 bytes → 32 bytes)
• ML-DSA-65 Authentication: ALL TLS handshake signatures use pure PQC
• No Classical Keys: Ed25519 completely removed, pure ML-DSA-65 only

Trust Model

• TOFU (Trust On First Use): First contact stores ML-DSA-65 public key fingerprint
• Rotation: New keys must be signed by old key (continuity)
• Channel Binding: TLS exporter signed with ML-DSA-65 (pure PQC)
• NAT/Path Changes: Token binding uses (PeerId || CID || nonce)

Installation

From Crates.io

cargo add saorsa-transport

Pre-built Binaries

Download from GitHub Releases:

• Linux: saorsa-transport-linux-x86_64, saorsa-transport-linux-aarch64
• Windows: saorsa-transport-windows-x86_64.exe
• macOS: saorsa-transport-macos-x86_64, saorsa-transport-macos-aarch64

From Source

git clone https://github.com/WithAutonomi/saorsa-transport
cd saorsa-transport
cargo build --release

Binary Usage

# Run as P2P node (auto-connects to default bootstrap nodes)
saorsa-transport --listen 0.0.0.0:9000

# Connect to specific known peers
saorsa-transport --listen 0.0.0.0:9000 --known-peers 1.2.3.4:9000 --known-peers 5.6.7.8:9000

# Show your external address (discovered via peers)
saorsa-transport --listen 0.0.0.0:9000
# Output: External address: YOUR.PUBLIC.IP:PORT

# Run with monitoring dashboard
saorsa-transport --dashboard --listen 0.0.0.0:9000

# Interactive commands while running:
# /status - Show connections and discovered addresses
# /peers  - List connected peers
# /help   - Show all commands

Default Bootstrap Nodes

If no --known-peers are specified, saorsa-transport automatically connects to the Saorsa Labs bootstrap nodes:

• saorsa-1.saorsalabs.com:9000
• saorsa-2.saorsalabs.com:9000

These nodes run the same saorsa-transport software as any peer - they help with initial peer discovery and external address observation.

API Reference

Primary Types

Type	Purpose
P2pEndpoint	Main entry point for P2P networking
P2pConfig	Configuration builder
P2pEvent	Events from the endpoint
PeerId	32-byte peer identifier
PqcConfig	Post-quantum crypto tuning
NatConfig	NAT traversal tuning

P2pEndpoint Methods

impl P2pEndpoint {
    // Creation
    async fn new(config: P2pConfig) -> Result<Self>;

    // Identity
    fn peer_id(&self) -> PeerId;
    fn local_addr(&self) -> Option<SocketAddr>;
    fn external_address(&self) -> Option<SocketAddr>;

    // Connections
    async fn connect_bootstrap(&self) -> Result<()>;
    async fn connect_to_peer(&self, peer: PeerId) -> Result<Connection>;
    fn connected_peers(&self) -> Vec<PeerId>;

    // Events
    fn subscribe(&self) -> broadcast::Receiver<P2pEvent>;

    // Statistics
    fn stats(&self) -> EndpointStats;
    fn nat_stats(&self) -> NatTraversalStatistics;
}

P2pConfig Builder

let config = P2pConfig::builder()
    .bind_addr("0.0.0.0:9000".parse()?)  // Local address
    .known_peer(addr1)                    // Add known peer
    .known_peers(vec![addr2, addr3])      // Add multiple
    .max_connections(100)                 // Connection limit
    .pqc(pqc_config)                      // PQC tuning
    .nat(nat_config)                      // NAT tuning
    .mtu(MtuConfig::pqc_optimized())      // MTU for PQC
    .build()?;

See docs/API_GUIDE.md for the complete API reference.

RFC Compliance

saorsa-transport implements these specifications:

Specification	Status	Notes
RFC 9000	Full	QUIC Transport Protocol
RFC 9001	Full	QUIC TLS
Pure PQC Auth	Full	Raw Public Keys + Pure PQC (v0.2)
draft-seemann-quic-nat-traversal-02	Full	NAT Traversal
draft-ietf-quic-address-discovery-00	Full	Address Discovery
FIPS 203	Full	ML-KEM (via saorsa-pqc)
FIPS 204	Full	ML-DSA (via saorsa-pqc)

See docs/review.md for detailed RFC compliance analysis.

Performance

Connection Establishment

Metric	Value
Handshake (PQC)	~50ms typical
Address Discovery	<100ms
NAT Traversal	200-500ms
PQC Overhead	~8.7%

Data Transfer (localhost)

Metric	Value
Send Throughput	267 Mbps
Protocol Efficiency	96.5%
Protocol Overhead	3.5%

Scalability

Connections	Memory	CPU
100	56 KB	Minimal
1,000	547 KB	Minimal
5,000	2.7 MB	Linear

System Requirements

• Rust: 1.88.0+ (Edition 2024)
• OS: Linux 3.10+, Windows 10+, macOS 10.15+
• Memory: 64MB minimum, 256MB recommended
• Network: UDP traffic on chosen port

Documentation

• API Guide - Complete API reference
• Symmetric P2P - Architecture explanation
• NAT Traversal Guide - NAT traversal details
• PQC Configuration - PQC tuning
• Architecture - System design
• Troubleshooting - Common issues

Examples

# Simple chat application
cargo run --example simple_chat -- --listen 0.0.0.0:9000

# Chat with peer discovery
cargo run --example chat_demo -- --known-peers peer.example.com:9000

# Statistics dashboard
cargo run --example dashboard_demo

Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Specific test categories
cargo test nat_traversal
cargo test pqc
cargo test address_discovery

# Run benchmarks
cargo bench

Contributing

Contributions welcome! Please see CONTRIBUTING.md.

# Development setup
git clone https://github.com/WithAutonomi/saorsa-transport
cd saorsa-transport
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Acknowledgments

• Built on Quinn QUIC implementation
• Pure PQC powered by saorsa-pqc - NIST FIPS 203/204 compliant ML-KEM and ML-DSA
• NAT traversal per draft-seemann-quic-nat-traversal-02
• Developed for the Autonomi decentralized network

Security

For security vulnerabilities, please email security@autonomi.com rather than filing a public issue.