Skip to content

feat: add QUIC transport backend as default fallback #37

@Jing-yilin

Description

@Jing-yilin

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 Transport interface in src/transport.ts
  • Refactor Yggdrasil code to implement Transport interface
  • Implement QUIC transport backend (evaluate @aspect-build/quiche or Node.js native QUIC)
  • Add automatic transport selection logic on startup
  • Update PeerRecord / PeerAnnouncement for 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions