ant-quic

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 ant_quic::{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

ant-quic 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.

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)

ant-quic 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

Powered by saorsa-pqc

ant-quic 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 ant_quic::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

Transport Parameters

NAT Type Support

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 ant-quic

Pre-built Binaries

Download from GitHub Releases:

• Linux: ant-quic-linux-x86_64, ant-quic-linux-aarch64
• Windows: ant-quic-windows-x86_64.exe
• macOS: ant-quic-macos-x86_64, ant-quic-macos-aarch64

From Source

git clone https://github.com/dirvine/ant-quic
cd ant-quic
cargo build --release

Binary Usage

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

# Connect to specific known peers
ant-quic --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)
ant-quic --listen 0.0.0.0:9000
# Output: External address: YOUR.PUBLIC.IP:PORT

# Run with monitoring dashboard
ant-quic --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, ant-quic automatically connects to the Saorsa Labs bootstrap nodes:

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

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

Bootstrap Cache

ant-quic maintains a local cache of discovered peers to improve startup time and resilience. The cache is stored as a JSON file:

The cache includes:

• Peer IDs and socket addresses
• Connection quality scores (RTT, success rate)
• NAT type hints for traversal optimization
• Last-seen timestamps for freshness

The cache is automatically managed - stale entries are pruned and high-quality peers are prioritized for reconnection.

API Reference

Primary Types

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

ant-quic implements these specifications:

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

Performance

Connection Establishment

Data Transfer (localhost)

Scalability

System Requirements

• Rust: 1.85.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/dirvine/ant-quic
cd ant-quic
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.