Implement QUIC Transport and Protocol Discovery for API Clients

[umwelt]

Summary

API clients need to implement QUIC transport to connect to SOVN nodes. The network has migrated to a QUIC-only architecture - TCP and UDP handlers have been deprecated and removed.

Connection Details

Transport Layer

• Protocol: QUIC (RFC 9000) over UDP
• Default Port: 9333
• TLS: Required (QUIC mandates TLS 1.3)
• Certificate Verification: Self-signed certificates are used in mesh mode

QUIC Client Requirements

Clients must:

1. Use a QUIC library (e.g., quinn for Rust, quic-go for Go, aioquic for Python)
2. Configure TLS to accept self-signed certificates (for mesh/development)
3. Open bidirectional streams for request/response patterns

Example Connection (Rust with Quinn)

```rust
use std::sync::Arc;
use quinn::{ClientConfig, Endpoint};

// Configure client to accept self-signed certs (for testing/mesh)
let crypto = rustls::ClientConfig::builder()
.dangerous()
.with_custom_certificate_verifier(Arc::new(InsecureCertVerifier))
.with_no_client_auth();

let client_config = ClientConfig::new(Arc::new(
quinn::crypto::rustls::QuicClientConfig::try_from(crypto)?
));

// Create endpoint and connect
let mut endpoint = Endpoint::client("0.0.0.0:0".parse()?)?;
endpoint.set_default_client_config(client_config);

let connection = endpoint
.connect("127.0.0.1:9333".parse()?, "localhost")?
.await?;

// Open bidirectional stream for HTTP-over-QUIC
let (mut send, mut recv) = connection.open_bi().await?;

// Send HTTP request
send.write_all(b"GET /api/v1/protocol/info HTTP/1.1\r\nHost: localhost\r\n\r\n").await?;
send.finish()?;

// Read response
let response = recv.read_to_end(1024 * 1024).await?;
```

Enabled Protocols & Discovery Methods

The SOVN unified server supports multiple peer discovery protocols:

Protocol	Status	Description
QUIC	✅ Primary	Native ZHTP-over-QUIC transport (port 9333)
UDP Multicast	✅ Active	LAN peer discovery (broadcasts every 30s)
mDNS	✅ Active	Service discovery via _zhtp._udp.local
WiFi Direct	✅ Active	P2P connections without router
Bluetooth LE	✅ Active	Mobile device connectivity via GATT
Bluetooth Classic	✅ Active	Legacy Bluetooth support
LoRaWAN	✅ Active	Long-range low-power mesh
ZHTP Relay	✅ Active	Encrypted DHT queries (Dilithium2 + Kyber512 + ChaCha20)

Deprecated (Removed)

• ❌ TCP Handler - Replaced by QUIC
• ❌ UDP Handler - Replaced by QUIC

API Endpoints Available

Once connected via QUIC, clients can access these HTTP endpoints:

Core APIs

• GET /api/v1/protocol/info - Protocol information
• GET /api/v1/protocol/health - Health check
• GET /api/v1/protocol/version - Version info

Identity Management

• /api/v1/identity/* - DID and identity operations

Blockchain Operations

• /api/v1/blockchain/* - Chain queries, transactions

Storage

• /api/v1/storage/* - Distributed storage operations
• /api/v1/dht/* - DHT queries

Other

• /api/v1/wallet/* - Wallet operations
• /api/v1/dao/* - DAO governance
• /api/v1/web4/* - Web4 content
• /api/v1/dns/* - ZDNS resolution

Post-Quantum Cryptography

The network uses post-quantum cryptography for mesh connections:

• Key Exchange: Kyber512 (ML-KEM)
• Signatures: Dilithium2 (ML-DSA)
• Symmetric Encryption: ChaCha20-Poly1305

Clients connecting to the mesh layer (not just HTTP API) need to implement the PQC handshake.

Tasks

• Implement QUIC transport layer
• Add TLS configuration for self-signed certificates
• Implement HTTP-over-QUIC request/response
• Add protocol discovery endpoint client
• Document connection examples for multiple languages
• Consider implementing native ZHTP protocol (beyond HTTP compatibility)
• Add PQC handshake for full mesh participation (optional, for advanced clients)

Reference Implementation

See the test client in the main repo:

• zhtp/src/bin/test_quic_client.rs - Simple QUIC test client

Related

• QUIC RFC 9000: https://www.rfc-editor.org/rfc/rfc9000.html
• Quinn (Rust QUIC): https://github.com/quinn-rs/quinn