Traylinx Stargate Network Specification¶
Date: 2025-12-10
Status: MVP Complete
Parent Document: Stargate Whitepaper
Executive Summary¶
Traylinx Stargate is a decentralized agent-to-agent (A2A) communication protocol enabling AI agents to discover, authenticate, and communicate with each other peer-to-peer—without requiring deployment to centralized servers.
Vision: An "Internet of Agents" where any developer can publish an agent from their laptop and have it be discoverable and callable by agents worldwide.
1. Problem Statement¶
Current AI agent deployment models have critical limitations:
| Problem | Impact |
|---|---|
| Centralized Hosting Required | Developers must deploy to AWS/GCP to make agents accessible |
| No Standard Discovery | No way for Agent A to find Agent B without hardcoded URLs |
| Siloed Communication | Each platform (OpenAI, Anthropic) has proprietary APIs |
| High Infrastructure Costs | Running 24/7 servers for rarely-used agents is wasteful |
2. Solution: The Stargate Protocol¶
2.1 Core Architecture¶
┌──────────────────────────────────────────────────────────────┐
│ TRAYLINX STARGATE NETWORK │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent A │◄───────►│ NATS │◄───────►│ Agent B │ │
│ │ (Mac) │ │ Server │ │ (Linux) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │ │
│ │ ┌────┴────┐ │ │
│ └─────────────►│ Agent C │◄─────────────┘ │
│ │ (Cloud) │ │
│ └─────────┘ │
│ │
│ Transport Options: │
│ • NATS (Default) - Hub-and-spoke via message broker │
│ • Libp2p (Alpha) - True peer-to-peer mesh │
│ │
└──────────────────────────────────────────────────────────────┘
2.2 Key Components¶
| Component | Description | Status |
|---|---|---|
| Identity Layer | Ed25519 keypair per agent, provides unique PeerID | ✅ Complete |
| Transport Layer | Pluggable (NATS or Libp2p) | ✅ Complete |
| Discovery Protocol | Publish/Subscribe announcements | ✅ Complete |
| A2A Messaging | Request/Response between agents | ✅ Complete |
3. Technical Specification¶
3.1 Identity Management¶
Each agent has a cryptographic identity:
{
"peer_id": "231cfb892e800b2602b69deab977a76c", # SHA256(public_key)
"public_key": "d632503d8afede77c4c389c37348dc00...", # Ed25519
"private_key": "<stored locally, never transmitted>"
}
Security Properties:
- Identity is self-sovereign (no central authority)
- Messages can be signed and verified
- Storage: ~/.traylinx/stargate/identity.json (mode 0600)
3.2 Transport Layer¶
3.2.1 NATS Transport (Default)¶
- Type: Centralized message broker
- Latency: ~10ms typical
- Reliability: High (production-grade)
- Default Server:
nats://demo.nats.io:4222(public testing)
Subject Schema:
| Subject | Purpose |
|---------|---------|
| traylinx.announce | Agent presence broadcasts |
| traylinx.discovery | Who's online requests |
| traylinx.agents.<peer_id> | Direct messages to specific agent |
3.2.2 Libp2p Transport (Production-Ready)¶
- Type: True peer-to-peer mesh with Circuit Relay v2
- Latency: Variable (direct: ~5-20ms, relayed: ~50-100ms)
- Reliability: High (production-ready with automatic failover)
- Security: Noise protocol encryption
NAT Traversal Features: - Circuit Relay v2: Enables communication through relay nodes when direct connection fails - Automatic NAT Detection: Detects network topology (public, private, symmetric NAT) - Connection Pooling: Reuses connections efficiently with automatic retry logic - Health Monitoring: Real-time relay node health checks with automatic failover - Metrics Collection: Comprehensive instrumentation for monitoring
Relay Node Infrastructure: - Public relay nodes with static IPs - Automatic relay discovery and selection - Load balancing across multiple relays - Graceful degradation when relays are unavailable
3.3 Discovery Protocol¶
Agent A Network Agent B
│ │ │
│──► PUBLISH announce ────►│ │
│ {peer_id, name, │──────────────────────────│
│ capabilities} │ │
│ │◄── SUBSCRIBE announce ──│
│ │ │
│ │ (Agent B sees │
│ │ Agent A) │
3.4 A2A Messaging Protocol¶
Message Format (JSON-RPC 2.0 Compatible):
{
"jsonrpc": "2.0",
"method": "search",
"params": {"query": "best restaurants in Berlin"},
"id": "req-12345",
"from": "231cfb892e800b2602b69deab977a76c"
}
Response:
4. Usage Examples¶
4.1 CLI Commands¶
# Generate identity (one-time)
traylinx stargate identity generate
# Connect to network
traylinx stargate connect --name "MyAgent"
# Discover other agents
traylinx stargate discover
# Call an agent
traylinx stargate call <peer_id> search '{"query": "hello"}'
4.2 Programmatic API¶
from traylinx_stargate import StarGateNode
async def main():
node = StarGateNode(
display_name="SearchAgent",
capabilities=["search", "translate"]
)
# Register handlers
@node.handler("search")
async def handle_search(action, payload, from_peer):
return {"results": do_search(payload["query"])}
# Start and announce
await node.start()
await node.announce()
# Discover peers
peers = await node.discover()
# Call another agent
result = await node.call(peers[0].peer_id, "translate", {
"text": "Hello",
"to": "German"
})
5. Network Architecture Vision¶
5.1 The "Agent Internet"¶
Traylinx Stargate implements a public, permissionless network—similar to blockchain networks:
| Property | Stargate | Ethereum |
|---|---|---|
| Join | Permissionless | Permissionless |
| Discovery | Via Gossip/DHT | Via DHT |
| Identity | Ed25519 Keys | ECDSA Keys |
| Consensus | Not needed (messaging only) | PoS |
5.2 NAT Traversal Strategy (Production Implementation)¶
Global connectivity from home networks is now fully operational:
┌────────────┐ ┌────────────┐
│ Agent A │ │ Agent B │
│ (Behind │ │ (Behind │
│ Router) │ │ Router) │
└─────┬──────┘ └──────┬─────┘
│ │
│ ┌──────────────────────────────────┐ │
└──►│ Circuit Relay v2 Node │◄───┘
│ (Public IP / Relay Service) │
│ │
│ 1. NAT detection & classification│
│ 2. Direct connection attempt │
│ 3. Circuit relay fallback │
│ 4. Connection pooling & reuse │
│ 5. Health monitoring & failover │
└──────────────────────────────────┘
Production Features: 1. Automatic NAT Detection: Agents detect their network topology on startup 2. Circuit Relay v2: Standards-compliant relay protocol with resource limits 3. Connection Pooling: Efficient connection reuse with configurable limits 4. Health Monitoring: Real-time relay health checks with automatic failover 5. Metrics & Observability: Comprehensive instrumentation for debugging
Deployment Architecture: - Multiple relay nodes in different regions for redundancy - Automatic relay discovery via DHT - Load balancing across healthy relays - Graceful degradation when relays are unavailable
See NAT Traversal Guide for detailed configuration and troubleshooting.
6. Implementation Status¶
6.1 Completed (v0.4.0)¶
| Feature | Status | Notes |
|---|---|---|
| Identity Management | ✅ | Ed25519, secure storage |
| NATS Transport | ✅ | Production-ready |
| Libp2p Transport | ✅ | Production-ready with Circuit Relay v2 |
| Circuit Relay v2 | ✅ | Standards-compliant relay protocol |
| NAT Detection | ✅ | Automatic network topology detection |
| Connection Pooling | ✅ | Efficient connection reuse |
| Health Monitoring | ✅ | Real-time relay health checks |
| Metrics Collection | ✅ | Comprehensive instrumentation |
| Discovery Protocol | ✅ | Automatic |
| A2A Messaging | ✅ | Request/Response |
| CLI Integration | ✅ | Plugin architecture |
| Token Auto-Refresh | ✅ | OAuth integration |
6.2 Future Roadmap¶
| Feature | Priority | Effort |
|---|---|---|
| DHT Peer Discovery Enhancement | 🟡 Medium | 2 weeks |
| Agent Capability Registry | 🟡 Medium | 2 weeks |
| Rate Limiting / Abuse Prevention | 🔴 High | 1 week |
| Relay Node Auto-Scaling | 🟢 Low | 2 weeks |
| Advanced Metrics Dashboard | 🟢 Low | 1 week |
7. Security Considerations¶
| Threat | Mitigation |
|---|---|
| Identity Spoofing | Messages signed with Ed25519 keys |
| Eavesdropping | NATS TLS / Libp2p Noise encryption |
| DoS / Message Flooding | 10MB message size limit |
| Malicious Agents | Future: Reputation system |
8. Conclusion¶
Traylinx Stargate provides the foundational infrastructure for a decentralized AI agent network. The core protocol is complete and functional—agents can discover and communicate with each other across different machines without centralized deployment.
The path to a global "Agent Internet" requires: 1. Bootstrap Node Deployment (NAT traversal) 2. DHT Integration (decentralized discovery) 3. Reputation/Trust System (optional, for quality control)
Appendix A: Glossary¶
| Term | Definition |
|---|---|
| PeerID | Unique identifier derived from agent's public key |
| NATS | High-performance message broker |
| Libp2p | Modular P2P networking stack |
| Gossipsub | Pub/Sub protocol for libp2p |
| NAT Traversal | Techniques to connect peers behind firewalls |
| STUN | Session Traversal Utilities for NAT |
| A2A | Agent-to-Agent communication |