-
Notifications
You must be signed in to change notification settings - Fork 0
Description
Summary
DeClaw currently requires Yggdrasil daemon installation for P2P connectivity. This is the single biggest adoption blocker — it gates 90%+ of potential users behind a non-trivial setup step.
Add QUIC as a second transport backend that works zero-install, zero-config as an automatic fallback when Yggdrasil is not available.
Motivation
DeClaw's mission is to provide networking infrastructure for trillion-scale agents. At that scale, every agent cannot install a daemon. QUIC is the right default transport because:
- Zero install — built on UDP, no daemon needed
- Fastest — 0-RTT connection establishment, native UDP
- Most adopted — 30%+ of global internet traffic runs on QUIC (Google, Cloudflare, Meta)
- Best NAT traversal — ICE/STUN built into the ecosystem
- IETF standard — RFC 9000, production-proven
Yggdrasil remains the "pure decentralized mode" for users who want cryptographic overlay routing.
Design
Transport Abstraction Interface
Define a Transport interface that both Yggdrasil and QUIC implement:
interface Transport {
readonly id: string // "yggdrasil" | "quic" | "native-ipv6"
readonly address: string // routable address on this transport
start(identity: Identity): Promise<void>
stop(): Promise<void>
send(target: string, data: Buffer): Promise<void>
onMessage(handler: (from: string, data: Buffer) => void): void
}Automatic Transport Selection
Agent starts
→ Detect Yggdrasil daemon? → Yes → Use Yggdrasil (200::/7 overlay)
→ No → Use QUIC (direct UDP, STUN-assisted NAT traversal)
Identity Preservation
QUIC does not provide "key = address" like Yggdrasil. DeClaw's Ed25519 identity layer must work independently:
- Agent ID remains
sha256(ed25519_pubkey)[:16] - DHT discovery maps agent ID → QUIC endpoint (host:port)
- Bootstrap nodes serve as STUN/rendezvous for NAT traversal
- Ed25519 signatures remain the trust anchor regardless of transport
Peer Discovery Changes
PeerRecord needs a transport-aware address field:
interface PeerRecord {
agentId: string
publicKey: string
endpoints: Array<{
transport: "yggdrasil" | "quic" | "native-ipv6"
address: string // ygg addr, or host:port for QUIC
priority: number
}>
// ... existing fields
}Tasks
- Define
Transportinterface insrc/transport.ts - Refactor Yggdrasil code to implement
Transportinterface - Implement QUIC transport backend (evaluate
@aspect-build/quicheor Node.js native QUIC) - Add automatic transport selection logic on startup
- Update
PeerRecord/PeerAnnouncementfor multi-transport endpoints - Update peer-server to accept connections from any transport
- Update peer-client to route via best available transport
- Update bootstrap nodes to support QUIC rendezvous
- Add tests for transport abstraction + QUIC backend
- Update SKILL.md and references
Non-goals (this issue)
- Tailscale support (future, enterprise-driven)
- x402 / ERC-8004 integration (separate issues)
- A2A Agent Card compatibility (separate issue)
References
- QUIC RFC 9000: https://datatracker.ietf.org/doc/html/rfc9000
- Node.js QUIC status: src: quic nodejs/node#44325
- NANDA "Upgrade or Switch" paper: agents need qualitative, not incremental, transport changes (arXiv:2506.12003)