# ant-node Design Document
## Overview
Build a **pure quantum-proof network node** (`ant-node`) that:
1. Uses `saorsa-core` for networking, NAT traversal, and PQC crypto
2. Stays clean - no legacy protocol dependencies
3. Auto-migrates local legacy ant-node data on startup
4. Implements auto-upgrade with ML-DSA signature verification
5. Supports dual IPv4/IPv6 DHT for maximum connectivity
6. Features geographic routing, Sybil resistance, and trust-based routing
## Architecture Philosophy
**Clean separation of concerns:**
- **ant-node** = Pure quantum-proof node (no legacy baggage)
- **ant-cli** = Client layer (file/chunk operations with EVM payments)
- **Auto-migration** = Nodes discover and upload local legacy ant-node data
- **Dual IP DHT** = IPv4 and IPv6 close groups for resilience
This avoids the complexity of bridge nodes by pushing migration logic to:
1. **Clients** - which naturally access data and can write to new network
2. **Node startup** - which can scan for local legacy ant-node data and migrate it
---
## Migration Strategy: Client-as-Bridge + Node Auto-Migration
### How Migration Works
```
+-------------------------------------------------------------+
| |
| +-----------+ +-----------------+ |
| | ant-network | <----> | ant-cli | |
| | (classical) | read | (client layer) | |
| +-----------+ +--------+--------+ |
| | write |
| v |
| +-----------------+ |
| +-----------+ | autonomi-network | |
| |ant-node data| ----->| (quantum-proof) | |
| | on disk | migrate | | |
| +-----------+ +-----------------+ |
| ^ ^ |
| | scan | |
| +-----+-----------------------+-+ |
| | ant-node | |
| | (pure quantum-proof node) | |
| +-----------------------------------+ |
| |
+-------------------------------------------------------------+
```
### Client Bridge Behavior
```rust
impl AutonomiClient {
async fn get_data(&self, address: &DataAddress) -> Result<Data> {
// 1. Try autonomi-network first (quantum-proof)
if let Ok(data) = self.autonomi_network.get(address).await {
return Ok(data);
}
// 2. Fall back to ant-network (legacy)
let data = self.ant_network.get(address).await?;
// 3. Migrate to autonomi-network (lazy migration)
self.autonomi_network.put(&data).await?;
Ok(data)
}
async fn put_data(&self, data: &Data) -> Result<DataAddress> {
// New data goes ONLY to quantum-proof network
self.autonomi_network.put(data).await
}
}
```
### Node Auto-Migration on Startup
```rust
impl AntNode {
async fn startup(&mut self) -> Result<()> {
// 1. Normal node startup
self.initialize_network().await?;
// 2. Scan for local legacy ant-node data directories
if let Some(ant_data_dir) = self.find_ant_node_data() {
info!("Found legacy ant-node data at {:?}, starting migration", ant_data_dir);
self.migrate_local_ant_data(ant_data_dir).await?;
}
Ok(())
}
async fn migrate_local_ant_data(&self, ant_dir: PathBuf) -> Result<MigrationStats> {
let reader = AntRecordStoreReader::new(&ant_dir)?;
let mut stats = MigrationStats::default();
for record in reader.read_all_records() {
// Store on autonomi-network
self.dht_manager.put(record.key, record.value).await?;
stats.migrated += 1;
}
Ok(stats)
}
}
```
### Key Design Decisions
| Migration Strategy | **Client-as-Bridge + Node Auto-Migration** | Clean node, organic migration |
| Node Architecture | **Pure quantum-proof (no libp2p)** | Simpler, more secure |
| Node Identity | Fresh ML-DSA Keypairs | Clean break, better privacy |
| Network Protocol | **Dual IPv4/IPv6 DHT** | Maximum connectivity and resilience |
| Geographic Routing | **Enabled** | No datacenter concentration |
| Sybil Resistance | **Required** | Prevent Sybil attacks |
| Node Reputation | **TrustEngine** | Measure and block bad nodes |
| Auto-Upgrade | Phase 1 Critical | Essential for network transition |
---
## Architecture
### Project Structure (Thin Wrapper - Leverages saorsa-core)
```
ant-node/
├── Cargo.toml
├── src/
│ ├── lib.rs # Library exports
│ ├── bin/
│ │ └── ant-node/
│ │ ├── main.rs # CLI entry point
│ │ ├── cli.rs # Command-line parsing (clap)
│ │ └── rpc_service.rs # Admin RPC service (optional)
│ │
│ ├── node.rs # RunningNode + NodeBuilder
│ │ # Thin wrapper around NetworkCoordinator
│ ├── config.rs # Configuration (wraps saorsa-core configs)
│ ├── event.rs # NodeEvent system
│ │
│ ├── migration/ # Legacy ant-node data migration (NEW CODE)
│ │ ├── mod.rs
│ │ ├── scanner.rs # Find legacy ant-node data directories
│ │ ├── ant_record_reader.rs # Decrypt AES-256-GCM-SIV records
│ │ └── uploader.rs # Upload via NetworkCoordinator
│ │
│ └── upgrade/ # AUTO-UPGRADE (NEW CODE - Critical)
│ ├── mod.rs
│ ├── monitor.rs # GitHub release polling
│ ├── signature.rs # ML-DSA binary verification
│ └── executor.rs # Process replacement + rollback
│
├── tests/ # Integration tests
│ ├── node_lifecycle.rs
│ ├── multi_node.rs
│ ├── migration.rs
│ └── upgrade.rs
│
└── README.md
```
**REMOVED** (provided by saorsa-core):
- `network/` - Use NetworkCoordinator + DualStackNetworkNode
- `trust/` - Use TrustEngine
- `storage/` - Use ContentStore
- `replication/` - Use ReplicationManager
### Core Components
**KEY INSIGHT: saorsa-core already provides ALL security, networking, and DHT features. ant-node is a thin wrapper!**
#### 1. AntNode (Thin Wrapper Around saorsa-core)
```rust
use saorsa_core::{
P2PNode, NodeConfig, NodeMode,
adaptive::trust::TrustEngine,
adaptive::dht::AdaptiveDhtConfig,
BootstrapConfig, BootstrapManager,
IPDiversityConfig,
identity::peer_id::PeerId,
};
pub struct RunningNode {
shutdown_sender: watch::Sender<bool>,
// USE ANT-CORE DIRECTLY - NO REIMPLEMENTATION!
node: Arc<P2PNode>, // Integrates ALL components
bootstrap: Arc<BootstrapManager>, // 30,000 peer cache
// Events
node_events_channel: NodeEventsChannel,
root_dir_path: PathBuf,
}
pub struct NodeBuilder {
node_config: NodeConfig, // saorsa-core's config
identity: saorsa_core::identity::NodeIdentity,
root_dir: PathBuf,
auto_migrate_ant_data: bool,
}
```
#### 2. Dual IPv4/IPv6 - ALREADY IN ANT-CORE!
**File:** `saorsa-core/src/messaging/network_config.rs`
```rust
// Just configure saorsa-core - it handles everything!
use saorsa_core::messaging::NetworkConfig;
// Option 1: Dual-stack on same port
let config = NetworkConfig::with_dual_stack();
// Option 2: Separate ports per IP version
let config = NetworkConfig::with_dual_stack_separate();
// Option 3: IPv4 only (default, safest)
let config = NetworkConfig::default();
// saorsa-core also implements Happy Eyeballs (RFC 8305)!
```
**DualStackNetworkNode already exists:**
```rust
// From saorsa-core/src/transport/ant_quic_adapter.rs
pub struct DualStackNetworkNode {
pub v6: Option<P2PNetworkNode>, // IPv6 stack
pub v4: Option<P2PNetworkNode>, // IPv4 stack
}
// Happy Eyeballs - race IPv6 and IPv4, return first success
pub async fn connect_happy_eyeballs(&self, targets: &[SocketAddr]) -> Result<PeerId>
```
#### 3. Sybil Resistance - ALREADY IN ANT-CORE!
**File:** `saorsa-core/src/security.rs` (1,245 lines)
```rust
// Just use saorsa-core's existing implementation!
use saorsa_core::security::{IPv6NodeID, IPDiversityEnforcer, IPDiversityConfig};
// Multi-layer subnet enforcement ALREADY IMPLEMENTED:
pub struct IPDiversityConfig {
pub max_nodes_per_64: usize, // Default: 1 per /64 subnet
pub max_nodes_per_48: usize, // Default: 3 per /48 allocation
pub max_nodes_per_32: usize, // Default: 10 per /32 region
pub max_nodes_per_asn: usize, // Default: 20 per ASN
// + GeoIP-based country limits
// + Halved limits for hosting/VPN providers
}
// IPv6-based node identity binding with ML-DSA signatures
pub struct IPv6NodeID {
pub node_id: [u8; 32], // SHA256(IPv6 || pubkey || salt || timestamp)
pub ipv6_addr: Ipv6Addr,
pub public_key: MlDsaPublicKey,
pub signature: MlDsaSignature,
}
```
#### 4. EigenTrust - ALREADY IN ANT-CORE!
**File:** `saorsa-core/src/adaptive/trust.rs` (825 lines)
```rust
// Just use saorsa-core's TrustEngine (formerly EigenTrust++)!
use saorsa_core::TrustEngine;
// Multi-factor trust scoring ALREADY IMPLEMENTED:
// - Response rate tracking
// - Connection success/failure monitoring
// - Time decay
// - Pre-trusted node bootstrap
// - Background computation
// Trust is accessed via P2PNode:
let score = node.peer_trust(&peer_id);
node.report_trust_event(&peer_id, TrustEvent::SuccessfulResponse);
```
#### 5. Geographic Routing - ALREADY IN ANT-CORE!
**File:** `saorsa-core/src/dht/geographic_routing.rs`
```rust
// Just use saorsa-core's geographic routing!
use saorsa_core::dht::geographic_routing::{GeographicRegion, LatencyAwareSelection};
// 7 geographic regions with cross-region preference scores
// Expected latency ranges per region (15-200ms)
// Latency-aware peer selection
// ASN diversity enforcement
```
#### 6. Security - ALREADY IN ANT-CORE!
```rust
// IP diversity enforcement for Sybil resistance
use saorsa_core::IPDiversityConfig;
// Multi-layer subnet enforcement ALREADY IMPLEMENTED:
// - Per-subnet limits (/64, /48, /32)
// - ASN diversity
// - Configurable via IPDiversityConfig::permissive() / ::testnet()
// Rate limiting and trust-based blocking handled by AdaptiveDHT
```
#### 7. P2PNode - INTEGRATES EVERYTHING!
**File:** `saorsa-core/src/network.rs`
```rust
// P2PNode brings ALL components together
// Access trust via:
node.trust_engine() // Arc<TrustEngine>
node.adaptive_dht() // &AdaptiveDHT
node.peer_trust(&peer) // Quick trust score lookup
node.report_trust_event(&peer, event) // Report trust signals
```
#### 8. What ant-node ACTUALLY Needs to Build
**Only these components are truly new:**
```rust
/// Auto-upgrade system (not in saorsa-core)
pub struct UpgradeMonitor {
github_repo: String, // "WithAutonomi/ant-node"
release_signing_key: MlDsaPublicKey, // Embedded in binary
check_interval: Duration, // Default: 1 hour
rollback_dir: PathBuf, // For failed upgrades
}
/// Legacy ant-node data migration (not in saorsa-core)
pub struct AntDataMigrator {
ant_data_dir: PathBuf,
// Reads AES-256-GCM-SIV encrypted records
// Uploads to autonomi-network
}
/// Node lifecycle and CLI (wrapper around saorsa-core)
pub struct NodeLifecycle {
node: Arc<P2PNode>,
upgrade_monitor: UpgradeMonitor,
migrator: Option<AntDataMigrator>,
}
```
---
## Implementation Phases
**KEY INSIGHT**: saorsa-core already provides:
- Dual IPv4/IPv6 with DualStackNetworkNode and Happy Eyeballs
- Sybil Resistance with IPv6NodeID and IPDiversityEnforcer
- TrustEngine with trust scoring and blocking
- Geographic Routing with 7 regions and latency-aware selection
- IP diversity enforcement for Sybil resistance
- P2PNode that integrates everything
**ant-node only needs to build**:
1. Auto-upgrade system (Phase 1 Critical)
2. Legacy ant-node data migration
3. Node lifecycle/CLI wrapper
4. Configuration/startup glue
### Phase 1: Repository Setup & Core Structure
- [ ] Initialize git repo, push to `WithAutonomi/ant-node` on GitHub
- [ ] Create Cargo.toml with saorsa-core, saorsa-pqc dependencies
- [ ] Create project structure
- [ ] Implement NodeBuilder that configures and creates NetworkCoordinator
- [ ] Implement RunningNode as thin wrapper around NetworkCoordinator
- [ ] Basic startup/shutdown lifecycle
### Phase 2: Auto-Upgrade System (CRITICAL)
**This is the one system that doesn't exist in saorsa-core**
- [ ] GitHub release monitor with configurable check interval
- [ ] ML-DSA-65 signature verification for binaries
- [ ] Process replacement with state preservation
- [ ] Rollback functionality (backup current binary)
- [ ] CLI flag: `--upgrade-channel`
### Phase 3: Legacy ant-node Data Migration
**Read and re-encrypt legacy ant-node records for the new network**
- [ ] Directory scanner for common legacy ant-node paths
- [ ] AES-256-GCM-SIV decryption (read-only, for migration)
- [ ] Upload via coordinator.dht.put() or coordinator.storage.store()
- [ ] Progress tracking and resume capability
- [ ] CLI flag: `--migrate-ant-data <path>`
### Phase 4: CLI & Configuration
- [ ] Create complete CLI with clap
- [ ] Configuration file support (TOML)
- [ ] RPC service for admin commands (optional)
### Phase 5: Integration Testing
- [ ] Single node startup/shutdown test
- [ ] Multi-node network test (local)
- [ ] DHT put/get test via NetworkCoordinator
- [ ] Migration test (mock legacy ant-node data)
- [ ] Auto-upgrade test (mock release)
- [ ] Test IPv4-only, IPv6-only, dual-stack scenarios
### Phase 6: Documentation & Release
- [ ] README.md with quick start
- [ ] API documentation
- [ ] Migration guide from legacy ant-node
- [ ] Release workflow with ML-DSA signing
- [ ] CI/CD pipeline (GitHub Actions)
---
## Key Design Decisions (Finalized)
### 1. Node Architecture: Pure Quantum-Proof (No Legacy)
- **No libp2p** - ant-node is clean, uses only ant-quic + saorsa-core
- **Client is the bridge** - ant-cli handles reading from ant-network
- **Node auto-migrates** - scans local legacy ant-node data and uploads to network
- **Rationale**: Simpler node, cleaner security model, easier maintenance
### 2. Storage Encryption: ChaCha20-Poly1305 (Quantum-Resistant)
- **Disk**: ChaCha20-Poly1305 (new format, not legacy ant-node compatible)
- **Network**: ML-KEM-768 for key exchange, ChaCha20-Poly1305 for symmetric
- **Migration**: Legacy ant-node data is read and re-encrypted during upload
- **Rationale**: Full quantum-resistance, clean break from legacy crypto
### 3. Identity: Fresh ML-DSA-65 Keypairs
- Generate completely new quantum-proof identity
- No derivation from legacy ed25519 keys
- **Rationale**: Clean break, better privacy, simpler implementation
### 4. Network: Dual IPv4/IPv6 DHT
- Separate close groups for IPv4 and IPv6
- Data replicated to BOTH for maximum redundancy
- IPv4-only and IPv6-only nodes participate fully in their respective DHTs
- Dual-stack nodes bridge between the two
- **Rationale**: Maximum connectivity, protocol resilience
### 5. Network Hardening
- **Geographic routing**: No datacenter concentration in close groups
- **Sybil resistance**: Join rate limiting, node age, resource verification
- **TrustEngine**: Node reputation and automatic bad node blocking
- **Rationale**: Production-grade security
### 6. Migration Strategy: Client-as-Bridge + Node Auto-Migration
- Client reads from both networks, writes to Autonomi network only
- Nodes scan for local legacy ant-node data and upload automatically
- Organic migration through usage
- **Rationale**: No bridge nodes, smooth transition
### 7. Auto-Upgrade: Phase 1 Critical with ML-DSA Verification
- All releases signed with ML-DSA-65 (quantum-proof signatures)
- Public key embedded in binary
- Rollback support for failed upgrades
- **Rationale**: Essential for coordinating network transition
---
## Dependencies
```toml
[dependencies]
# Core (provides EVERYTHING: networking, DHT, security, trust, storage)
saorsa-core = { path = "../saorsa-core" }
saorsa-pqc = { path = "../saorsa-pqc" } # ML-DSA for upgrade signature verification
# Migration: Decrypt legacy ant-node data (read-only)
aes-gcm-siv = "0.11" # Decrypt existing legacy ant-node records
hkdf = "0.12" # Key derivation for legacy ant-node format
# Async runtime
tokio = { version = "1.35", features = ["full"] }
# CLI
clap = { version = "4", features = ["derive"] }
# Configuration
serde = { version = "1", features = ["derive"] }
toml = "0.8"
# Auto-upgrade
reqwest = { version = "0.12", features = ["json", "rustls-tls"] }
semver = "1"
# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
# Error handling
thiserror = "2"
[dev-dependencies]
tempfile = "3"
tokio-test = "0.4"
```
**Note:**
- No libp2p - pure quantum-proof
- No maxminddb - saorsa-core handles GeoIP
- No blake3/chacha20poly1305 - saorsa-core handles encryption
- Only aes-gcm-siv for reading legacy ant-node data
---
## Risk Mitigation
### Migration Speed Risk
- **Risk**: Data migration may be slow if users don't access old data
- **Mitigation**: Node auto-migration uploads local legacy ant-node data proactively
- **Mitigation**: Popular data migrates first through client usage
- **Mitigation**: Optional bulk migration tool for operators
### IPv4/IPv6 Fragmentation Risk
- **Risk**: Networks may diverge if few dual-stack nodes
- **Mitigation**: Incentivize dual-stack node operators
- **Mitigation**: Geographic distribution of dual-stack nodes
- **Mitigation**: Data replicated to BOTH close groups for redundancy
### Sybil Attack Risk
- **Risk**: Attackers may try to dominate close groups
- **Mitigation**: Join rate limiting per subnet
- **Mitigation**: Node age requirements before full participation
- **Mitigation**: Resource verification challenges
- **Mitigation**: Geographic/ASN diversity enforcement
### EigenTrust Gaming Risk
- **Risk**: Nodes may try to game reputation system
- **Mitigation**: Multiple metrics (latency, uptime, success rate)
- **Mitigation**: Cross-validation between nodes
- **Mitigation**: Historical behavior weighting
### Auto-Upgrade Attack Risk
- **Risk**: Compromised release could spread to network
- **Mitigation**: ML-DSA-65 signatures on all binaries
- **Mitigation**: Multiple key holders for release signing
- **Mitigation**: Staged rollout with canary nodes
- **Mitigation**: Rollback functionality